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INTRODUCTION 

TSX-Plus is a high-performance operating system for Digital Equipment Corpo- 
ration PDP-11 and LSI-11 computers supporting up to 31 concurrent time-sharing 
users. TSX-Plus provides a multi-user programming environment that is similar 
to extended-memory (XM) RT-11. 

1. TSX-Plus keyboard commands are compatible with those of RT-11. 

2. TSX-Plus supports most RT-11 system service calls (EMTs). 

3. Most programs that run under RT-11 will run without modification 
under TSX-Plus. This includes RT-11 utility programs such as PIP, 
DUP, DIR, LINK, and MACRO. 

4. TSX-Plus uses RT-11 XM version device handlers. 

5. TSX-Plus provides PLAS extended memory services such as virtual 
overlays and virtual arrays, as well as support for extended memory 
regions. 

TSX-Plus can simultaneously support a wide variety of jobs and programming 
languages including COBOL-Plus, FORTRAN, BASIC, DIBOL, DBL, Pascal, C, MACRO, 
TECO and KED. TSX-Plus is used in educational, business, scientific and 
industrial environments. It can concurrently support commercial users doing 
transaction processing, engineering users performing scientific processing, 
system programmers doing program development, and real-time process control. 
Numerous application software packages compatible with TSX-Plus are available 
from other vendors. 

TSX-Plus supports RT-11 system service calls (EMTs) as its basic mode of 
operation. The result is low system overhead and substantially improved 
performance over systems that emulate RT-11 services. TSX-Plus overlaps 
terminal interaction time, I/O wait time, and CPU execution time for all jobs 
on the system. The result is a tremendous increase in the productivity of the 
computer system. 

In addition to the basic RT-11 functionality, TSX-Plus provides extended 
features such as: shared file record locking; inter- job message communication; 
program performance monitoring; command file parameters; logon and usage 
accounting; directory and data caching; multitasking; and system I/O buffering. 

This manual describes all the features unique to TSX-Plus as well as any 
differences from RT-11. Many of the special features of TSX-Plus are available 
as EMTs available to the MACRO programmer. Access to these features from other 
languages requires the appropriate subroutine interfacing. 

TSX-Plus will run on any PDP-11 or LSI-11 computer with memory management 
hardware and at least 128Kb of memory. The system must also have a disk 
suitable for program swapping (the swapping disk can be used for regular file 
storage as well). Time-sharing lines can be connected to the system through 
DL-11 or DZ-11 communication devices. Both hard-wired and dial-up lines are 
supported by TSX-Plus. 
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Introduction 

MANAGEMENT OF SYSTEM RESOURCES 

Memory Management 

TSX-Plus uses the memory management facilities of PDP-11 computers to keep 
several user jobs in memory simultaneously and switch rapidly among them. 
TSX-Plus protects the system by preventing user jobs from halting the machine 
or storing outside their program regions. TSX-Plus provides several ways to 
control the amount of memory used by individual jobs. Programs may be allowed 
to use up to 64Kb of memory and, if additional space is needed, may also use 
extended memory regions, virtual overlays and virtual arrays. The system 
manager may enable job-swapping to accommodate more user jobs than can fit in 
existing memory. 

Execution Scheduling 

TSX-Plus provides fast response to interactive jobs but minimizes job-swapping 
by use of an efficient job-scheduling algorithm. TSX-Plus permits job 
scheduling on both an absolute priority basis and by a method based on job 
states. For most applications, the method based on job states is preferred. 
The state-driven method provides the most transparent time-sharing scheduling, 
suitable for interactive environments. The absolute priority method always 
runs the highest priority executable job, when not servicing interrupts, 
regardless of that job's state. This state-free method is most suitable for an 
environment in which several real-time jobs must be assigned absolute priori- 
ties. TSX-Plus permits both kinds of jobs to co-exist in the same system, with 
interactive jobs being scheduled whenever higher priority state-free jobs are 
not executing. 

Job priorities may be assigned over a range of to 127. The lowest priority 
jobs, typically to 19, are reserved for fixed priority jobs which can soak up 
system idle time without disturbing interactive or real-time jobs. The medium 
priority range, typically 20 to 79, is assigned to interactive jobs which are 
scheduled according to a unique and efficient algorithm which makes time- 
sharing nearly transparent to several users. The highest priority range, 
typically 80 to 127, is reserved for jobs which must execute according to a 
rigid priority scheme such as might be found in a real-time environment. In 
addition, real-time jobs may execute interrupt service routines at fork level 
processing or schedule interrupt completion routines to run as fixed-high- 
priority jobs. 

Job scheduling is controlled by several system parameters relating job 
priorities, system timing and other events. The TSX-Plus System Manager's 
Guide includes a more complete description of job priority and scheduling. 

Directory and Data Caching 

TSX-Plus provides a mechanism to speed up directory operations by caching 
device directories. This reduces disk I/O necessary to open existing files. 
Caching of file data is also possible to further improve system throughput. 
The information kept in the cache buffers is managed according to a least- 
recently-used algorithm. Directory and data caching are discussed in the 
System Manager's Guide. 
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System Administrative Control 

TSX-Plus allows the system manager to limit access to the system through a 
logon facility and to restrict user access to peripheral devices. These 
features are described in the TSX-Plus System Manager's Guide. 
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SUMMARY OF CHAPTER CONTENTS 

Starting Time-sharing Sessions 

Chapter 1 of this manual describes the procedure for starting and stopping a 
time-sharing session with TSX-Plus; the special functions of some control- 
characters; and use of the single line editor for correction of typing errors 
in command lines or data entry fields. 

Keyboard Commands 

TSX-Plus responds to keyboard commands that are simple and natural (PRINT, RUN, 
COMPILE, TYPE, etc.)* TSX-Plus also provides user-definable commands, and 
includes support for a menu driven command interface. Chapter 2 discusses 
command interpretation sequence, user-defined commands, the menu interface and 
lists all TSX-Plus keyboard commands. It provides full descriptions of 
commands unique to TSX-Plus, describes differences between TSX-Plus and RT-11 
commands, and lists the RT-11 commands which are not supported by TSX-Plus. 
Many of the commands are identical to their RT-11 counterparts and the RT-11 
System User's Guide should be consulted for detailed descriptions. 

Command Files 

Frequently used sets of commands may be stored in a disk file and executed by 
invoking the command file. Parameters may be passed to the command file and 
interpreted as though they were included at designated places in the file. 
This provides an alternative way for users to create their own commands. 
Command files are described in Chapter 3. 

Virtual Lines and Detached Jobs 

TSX-Plus provides a facility known as "virtual lines" that allows one time- 
sharing user to simultaneously control several programs from a single terminal. 
The user may logically switch among the primary and virtual lines at any time. 
When a program that is not currently connected to a time-sharing line writes 
output to the terminal, the output is stored in a system buffer. When the 
buffer is filled, the program is suspended until the user reattaches to the 
program and accepts the queued output. Virtual lines are useful in situations 
in which it is desirable to run a long "number crunching" job without tying up 
a terminal. Detached jobs are similar, but are not associated with any 
terminal. Virtual lines and detached jobs are discussed in Chapter 4. 

Printer Spooling System 

TSX-Plus provides a convenient and powerful facility for automatic spooling of 
output to line printers and other devices. The spooler may simultaneously 
drive several devices. If the line printer is spooled, then simply directing 
output to device "LP" from a program causes the output to be spooled. A 
spooled file may designate the name of a form on which it is to be printed. 
When a form change is required, the spooled device is suspended and a message 
is sent to the operator requesting the form. After mounting the new form, the 
operator may print a form alignment file. Once a form is mounted, all files 
requiring the form are printed without further operator intervention. The 
operator may also lock a particular form on the printer, preventing automatic 
form change requests. Keyboard commands are provided to check the status of 
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spooled devices, delete files from the output queue, and reprint the most 
recent portion of the current file. Files sent to a spooled device may be 
released to the printer as data becomes available or held until the output file 
is closed. The spooling system is discussed in Chapter 5. 

Program Controlled Terminal Options 

TSX-Plus allows the programmer to modify terminal handling characteristics 
during program execution. For example, a program may disable character 
echoing, use single character activation, use high efficiency output mode, 
enable lower case input, activate on field width, or disable automatic echoing 
of line-feed after carriage-return. These terminal options may be selected 
either by issuing the appropriate EMT request or by writing a special sequence 
of two or three characters to the terminal. Chapter 6 discusses the use of 
terminal options during program execution. 

TSX-Plus EMTs 



TSX-Plus supports most of the system service calls (EMTs) provided by RT-11 
and, in addition, provides many more to utilize the special features of 
TSX-Plus. For example, EMTs are provided to determine the TSX-Plus line number 
and the user name, to send messages to another time-sharing line, to check for 
terminal input errors, and to check for activation characters. EMTs related to 
specific features, such as detached jobs or real-time programming, are 
described in the relevant chapters. The TSX-Plus EMTs which are not closely 
related to features described elsewhere are discussed in Chapter 7. 

User Memory Mapping 

TSX-Plus supports the use of extended memory regions through EMT calls 
compatible with those provided by the RT-11 XM monitor. This allows the use of 
virtual overlays and FORTRAN virtual arrays. Users can also expand programs to 
use the full 16-bit virtual address space. That is, by giving up access to the 
I/O page and direct access to fixed offsets in RMON, a program may address a 
full 64Kb. User control of extended memory and virtual job space is discussed 

-l t> PVi o ^ *- a v 8 

Shared Files and Data Caching 

TSX-Plus provides a file sharing mechanism whereby several cooperating programs 
may coordinate their access to common data files. Programs may request 
different levels of shared file access, and control shared access on a 
record-by-record basis. Two methods of data caching are also provided: 1) 
general data earning which is enabled when devices are MOUNTed; and 2) record 
caching which is only available to shared files. Directory caching is also 
enabled by the MOUNT request. This accelerates directory searching for file 
LOOKUPS. The use of shared files and data caching is described in Chapter 9. 

Inter-program Message Communication 

TSX-Plus offers a message communication facility that allows running programs 
to exchange messages. Messages are transmitted through named "message 
channels". A program can queue messages on one or more message channels. 
Receiving programs can test for the presence of messages on a named channel and 
can suspend their execution until a message arrives. A message can be queued 
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for a program that will run at a later time. The message facility is discussed 
in Chapter 10 

Real-time Support 

TSX-Plus provides real-time program support services that allow multiple 
real-time programs to run concurrently with normal time-sharing operations. 
Real-time programs may optionally lock themselves in memory, directly access 
the I/O page, redefine their memory mapping, and connect device interrupts to 
subroutines within the program. Real-time support is discussed in Chapter 11. 

Shared Run-time System Support 

TSX-Plus allows one or more shared run-time systems to be mapped into the 

address space of multiple TSX-Plus time-sharing jobs. This saves memory space 

when multiple users are running the same types of programs (e.g., COBOL-Plus or 

DBL) and can also be used in situations where programs wish to communicate 

through a shared data region. Shared run-time systems are discussed in Chapter 

12. 

Performance Analysis Facility 

TSX-Plus includes a performance analysis facility that can be used to monitor 
the execution of a program and determine what percentage of the run time is 
spent within certain program regions. When the performance analysis facility 
is being used, TSX-Plus examines the program being monitored at each clock tick 
(50 or 60 times per second) and notes the value of the program counter. On 
completion of the analysis, the TSX-Plus performance reporting program can 
produce a histogram of the time spent in various parts of the monitored 
program. Performance analysis is discussed in Chapter 13. 

Differences from RT-11 

Some inevitable differences exist between RT-11 and TSX-Plus. Chapter 2 
describes the additional keyboard commands provided by TSX-Plus, the minor 
differences in some commands, and the RT-11 keyboard commands not supported by 
TSX-Plus. Some other differences between RT-11 and TSX-Plus may not be 
obvious. The FORMAT utility is not supported. A few system service calls 
(EMTs) behave slightly differently in the two systems and some RT-11 EMTs are 
not supported by TSX-Plus (notably those supporting multi-terminal operations). 
These differences are detailed in Chapter 14. 

Appendices 

Appendix A describes the SETSIZ utility program which may be used to control 
the amount of memory available to programs. Appendix B describes a library of 
subroutines which are available to the DIBOL user to take advantage of some of 
the special features of TSX-Plus. Appendix C describes the FILTIM utility 
which displays directory information about files, including the file creation 
time. Appendix D provides a table of EMT function and subf unction codes, and 
brief descriptions of both RT-11 and TSX-Plus EMTs; these are useful in 
conjunction with the SET EMT TRACE command. Appendix E contains listings of 
common subroutines called by the example programs throughout this manual. 
Appendix F contains explanations of monitor error messages; fatal system error 
messages are covered in the TSX-Plus System Manager's Guide. Appendix G 
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describes the commands and techniques used to work with logical subset disks. 
Appendix H describes job execution priorities. 
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1. BASIC OPERATION 

1.1 Logging on 

Each user communicates with the TSX-Plus system through a time-sharing line 
(often referred to in this manual simply as a "line"). The system manager may 
designate lines to automatically initiate time-sharing whenever the system is 
started. Otherwise, lines are started by typing a carriage return or control-C 
at the terminal. In either case, when each line is first started, a greeting 
message will be displayed at the terminal. 

The system manager may assign a start-up command file to be executed whenever a 
time-sharing line is started. A start-up command file contains initialization 
commands for a line. It can end by either starting execution of some program, 
or by waiting for a system command. (The keyboard monitor prompt is a period.) 
It is possible for a start-up command file to lock a program to a line so that 
on termination of the program the line is automatically logged off and an 
optional log-off command file is executed. Typing control-C will not abort 
start-up or log-off command files. 

The system manager may also require "log on" authorization. In this case, the 
system manager assigns each user a user name (and project, programmer number) 
and password. After the greeting message, the message "Logon please:" is 
printed. The user responds by typing the user name (or pro ject, programmer 
number) followed by carriage return. TSX-Plus then requests the password. The 
password is not echoed to the terminal as it is typed. After the user name (or 
pro ject, programmer number) and password are validated, TSX-Plus types the 
message "Welcome to the system". The system manager may also designate a 
"start-up" command file for each account to control system access and set 
certain operating parameters. 

The following example illustrates a typical log-on sequence. The information 
typed by the user is underlined. 

(carriage return pressed) 

( ^ ) 

(greeting message) 

( ) 

23-Jan-84 13:39:50 
Line #2 



Logon please: JOHNSON 

Password : MYPASS (Password is not displayed.) 

Welcome to the system 

(TSX-Plus is now waiting for a system command.) 

A user may adopt a new password while logging on. To do this, enter a slash 
and the new password immediately after typing the old password. The new 
password must then be used for future logons. Passwords may be from 1 to 7 
characters in length and must be composed only of letters and digits. The 
following example shows the password being changed from "OLDP" to "NEWP". Note 
that neither the old nor the new password would actually be echoed. 
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(carriage return pressed) 
( ) 

(greeting message) 

( ) 

20-Jun-83 14:17:43 
Line #5 



Logon please: 107 > 24 
Password : OLDP/NEWP 
Welcome to the system 



(Either user name or PPN may be used.) 
(Passwords are not displayed.) 



If the system manager has not required "log on" account authorization, then the 
system will either execute a start-up command file or simply display the 
monitor prompt (".") and wait for a system command to be entered. 

1.2 Logging off 

The OFF keyboard command is used to terminate ("log off") a time-sharing 
session. 

The system manager may specify a "log off" command file to be executed whenever 
a job logs off. Control-C will not abort a "log off" command file. 
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1.3 Control characters 



Certain control characters have special meaning to the system. These "control 
characters" control certain terminal operations. They are entered by holding 
down the "CTRL" key while pressing the selected character. 

CTRL-C - Interrupts the current program and returns control to the 
keyboard monitor. If the running program is not waiting for 
input, two successive CTRL-C's are required to interrupt its 
execution. CTRL-C will not interrupt start-up or log-off 
command files. 

CTRL-0 - Suppresses program output to the terminal until one of the 
following conditions occurs: 

1) A second CTRL-0 is typed 

2) The program returns to the monitor 

3) The running program issues a .RCTRLO EMT 

CTRL-Q - Resumes printing on the terminal from the point at which 
printing was previously suspended by CTRL-S. CTRL-Q has no 
special effect if SET TT NO PAGE has been used. 

CTRL-R - Causes the current characters in the terminal input buffer to be 
displayed. This can be used to check the actual contents of an 



CTRL-S - Temporarily suspends output to trie terminal until oik.l,-^ is 
typed. CTRL-S has no special effect used if the SET TT NOPAGE 
command has been issued. 



CTRL-U - Deletes the current input line. 

CTRL-W - Used to switch to a TSX-Plus virtual line, 
more information on virtual lines.) 



(See Chapter 4 for 



CTRL-Z - Indicates end-of-file when input is being read from device "TT" . 

The normal function of these keys may be altered during program execution. 
Chapter 6 describes program controlled terminal options that influence these 
functions. When enabled, the single line editor defines additional special 
purpose keys; see the next section for further information about the single 
line editor. 
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1.4 Single Line Editor 

It is often desirable to correct typing mistakes made in the entry of command 
input lines or to correct data entry fields while executing some program. This 
can be done to a limited extent by use of the DELETE and Ctrl-U keys, however 
much more editing capability is available if the "Single Line Editor" facility 
is used. To use the single line editor, the system manager must enable it 
during the TSX-Plus system generation process. In addition, it must be turned 
on for each time-sharing line before use. To use the single line editor, issue 
the command: 

SET SL ON 

either in a start-up command file or as a keyboard command. The single line 
editor may be used only with VT100 or VT52 type terminals. 

Several other SET options are available for use with the single line editor. 
These are described in Chapter 2 in the section on keyboard commands. 

The single line editor accepts special key commands to direct its operation. 
Under TSX-Plus, there are two modes of operation of the single line editor: 
normal mode (RT-11 compatible); and KED mode. In normal mode, the TSX-Plus 
single line editor is compatible with the RT-11 single line editor except for 
the differences noted in the table at the end of this section. The following 
tables summarize the functions performed by the editing control keys. 
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Single Line Editor Key Functions 
Normal (RT-11 compatible) Mode 



1 




Primary Key Functions (Not prefixed by PFl) 


1 


1 

H 


Key 


1 Function 
H 


1 
+ 



I Up arrow 

I Down arrow 

I Left arrow 

i Right arrow 

| BACK SPACE 

j DELETE 

I LINE FEED 

I RETURN 

j PFl 

| PF2 

j pF3 

I PF4 

I Ctrl-U 
Ctrl-R 



Retrieve previous input lines 

Retrieve line from save buffer 

Move cursor left one character 

Move cursor right one character 

Exchange char under cursor with char to right 

Delete character to left of cursor 

Delete word to left of cursor 

Pass current line to running program 

Used before other keys to perform second funct 

Not implemented 

VT52: Delete from cursor to right end of line 

VT100: Delete from cursor to right end of line 

Delete from cursor to left end of line 

Redisplay current line 



ion 



+- 



Secondary Functions (Keys Prefixed by PFl) 

-H 

I Function 



Key 



Up arrow 
Down arrow 

T a -p +• -> -•• -*» m.T 
UCJL U OLLUW 

Right arrow 

BACK SPACE 

DELETE 

LINE FEED 

RETURN 

PFl 

PF2 

PF3 

PF4 

Ctrl-U 



Retrieve previous input lines (PFl is ignored) 

Save current line in "save buffer" for recall later 

Move cursor to left end of line 

Move cursor to right end of line 

Exchange char under cursor with char to left 

Retrieve last deleted character 

Retrieve last deleted word 

Truncate from cursor to end of line and execute 

Ignored 

Not implemented 

VT52: Retrieve last deleted line 

VT100: Retrieve last deleted line 

Retrieve last deleted line 



-+ 
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In addition to the normal (RT-11 compatible) mode of operation for the single 
line editor, TSX-Plus also permits use of some of the keypad functions in a 
fashion similar to KED (or K52). These keypad operations are available in 
addition to the functions described above for the single line editor. In order 
to use the extended (KED) mode with the single line editor, issue the following 
command: 

SET SL KED 

When the KED mode is enabled, the following tables describe the additional 
functions available to the single line editor. 

Single Line Editor Key Functions 

KED Mode 



Key 



ENTER 



Primary Key Functions (Not prefixed by PF1) 
I Function 



-+ 
-+ 



Move cursor to left end of line 

Move cursor one word in current direction 

Move to end of line in current direction 

VT100: Move cursor one char in current direction 

Set direction forward (left to right) 

Set direction backward (right to left) 

VT52: Delete character under cursor 

Not implemented 

Not implemented 

VT52: Delete word under cursor 

VT100: Delete word under cursor 

VT100: Delete character under cursor 

Pass current line to running program 



-+ 
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-+ 



Key 



Secondary Functions (Keys Prefixed by PF1) 

-H 

I Function 



ENTER 



Delete from cursor to right end of line 

Change case of char under cursor 

Delete from cursor to right end of line 

Not implemented 

Move cursor to right end of line 

Move cursor to left end of line 

VT52: Retrieve last deleted character 

Not implemented 

Not implemented 

VT52: Retrieve last deleted word 

VT100: Retrieve last deleted word 

VT100: Retrieve last deleted character 

Truncate from cursor to end of line and execute 



-+ 



To return the single line editor to the normal mode, issue the command: 

SET SL NOKED 
To disable the single line editor altogether, issue the command: 

SET SL OFF 

In addition to editing command lines, the single line editor may be used to 
edit data entry fields during program execution. However, there are some 
restrictions on such use. If any of the following conditions exist, then the 
single line editor may NOT be used to edit program data fields: 

1) The SET SL OFF command has been issued 

2) Bit 4 (EDIT$, mask 20) is set in the Job Status Word (JSW) 

3) Bit 12 (TTSPC$, mask 10000) is set in the JSW 

4) The program is using high-efficiency terminal mode 

5) The program is using escape sequence activation 

6) Input is being accepted via the .TTYIN EMT (except as below) 
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In order to use the single line editor to edit data entry fields within 
programs which accept input via the .TTYIN EMT, the following command must be 
issued prior to execution of the program: 

SET SL TTYIN 

Since COBOL-Plus programs accept terminal input via the .TTYIN EMT, the 
following steps must be used to edit data entry fields while executing 
COBOL-Plus programs: 

1) SET SL ON 

2) SET SL TTYIN 

3) From within the executing program, CALL "ESCAPE -OFF" 

The TSX-Plus single line editor is generally compatible with that provided with 
RT-11, with the following exceptions: 

1) The "Help" key (PF2) is not implemented. 

2) The SET SL LEARN mode is not implemented. 

3) The SET SL ASK option is ignored. (The current TSX-Plus terminal 
type information is used.) 

4) The SET SL SYSGEN option is ignored. 

5) The maximum width of a command line or input field that is accepted 
is 80 characters. The SET SL WIDTH=n option is ignored. 

6) The line feed key deletes the word to the left of the cursor. 
Technically, characters to the left of the cursor are deleted until 
one of the following delimiters is reached: space, tab, comma, or 
equal sign. 

7) The up arrow key can be used to retrieve either of the last two 
lines. Pressing the up arrow key cycles between recalling the last 
input line and the line prior to that. 

8) Using the single line editor with .TTYIN input does not force a new 
line. 

9) The single line editor is implemented as a TSX-Plus overlay region 
and does not require the SL pseudo-device handler. 
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2.1 Keyboard command interpretation 

When a system command line is typed in, TSX-Plus attempts to interpret it by 
sequentially applying the following rules: 

1. If the User Command Interface is in effect, then each time TSX-Plus 
is ready to accept a keyboard command it passes control to the 
current UCI program. The UCI program may be selected with the SET 
KMON UCI[=filnam] command. See the description of SET KMON command 
and the section in this chapter on the User Command Interface for 
more information. 

2. If the command line begins with an "at-sign" ("@"), TSX-Plus attempts 
to execute a command file. If no device is specified with the 
command file name, device "DK: " is assumed. The default extension 
for command files is "COM". If the SET KMON IND command has been 
issued, command files will execute under the control of the IND 
program. Command files may be specified for execution as normal 
command files, regardless of whether KMON is set IND or NOIND, by 
starting the command with a dollar-sign (e.g. "$@filnam"). Con- 
versely, command files can be forced to execute under the IND 
utility, regardless of whether KMON is set IND or NOIND, by typing: 
"IND filnam". 

See Chapter 3 for further information on the execution of command 
files by TSX-Plus. 

-» » ■■-■■- vhj*-*. uvi.iUvu I.UUUUU11UO null. L/W^.1.1. t* -I. J. >-» W C V-l UUl J.Llg X. kj£\. 1. J.UO gCUClO 

tion, and if UCL is set FIRST either in TSGEN or subsequently by the 
keyboard SET UCL FIRST command, then commands are checked at this 
point to see if they are user-defined commands. However, if the 
first character on a command line is the underline character (" ") 
then the command on that line is not checked to see if it is a 
user-defined command. See the next section for more information on 
user— defined commands- 

4. TSX-Plus next attempts to identify a command as a standard system 
command such as COPY, RUN, EXECUTE, etc. Commands may be abbreviated 
to the minimum number of characters that uniquely specify the name. 
Thus "COP" would be an acceptable abbreviation for COPY, but "CO" 
would not because it could mean COPY or COMPILE. "COPX" also would 
not be identified as a system command. 

5. If user-defined commands have been allowed during TSX-Plus genera- 
tion, and if UCL is set MIDDLE either in TSGEN or subsequently by the 
keyboard SET UCL MIDDLE command, then commands are checked at this 
point to see if they are user-defined commands. However, if the 
first character on a command line is the underline character (" ") 
then the command on that line is not checked to see if it is a 
user-defined command. 
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6. If the command has not yet been identified, then TSX-Plus tries to 
find a command file on device "DK:" that has the same name as the 
command keyword. If no such command file is found on "DK: " , TSX-Plus 
looks for the command file on device "SY:". In either case, if the 
SET KMON IND keyboard command has been issued, it will be executed 
under control of the IND program. When a command file is started in 
this fashion (rather than explicitly specifying an at-sign before its 
name), the command file listing is suppressed as if an implied "SET 
TT QUIET" command was executed during command startup. This implied 
listing suppression is temporary in effect and applies only to the 
command file started in this fashion. See Chapter 3 for more 
information on command files. 

7. If a command file cannot be found, TSX-Plus looks for an executable 
program (SAV file) on device "SY:" that has the same name as the 
command keyword. If such a program is found, it is executed as if 
there were an "R" command in front of the program name. Note that 
while both RT-11 and TSX-Plus allow a line of text input to be passed 
to a program with the RUN command by specifying it after the program 
name, TSX-Plus also allows this to be done with the "R" command and 
with an implied "R" command line when the program name is specified 
as the command keyword. See example 6 below. 

8. If user-defined commands have been allowed during TSX-Plus genera- 
tion, and if UCL is set LAST either in TSGEN or subsequently by the 
keyboard SET UCL LAST command, then commands are checked to see if 
they are user-defined commands at this point. However, if the first 
character on a command line is the underline character ("_") then the 
command on that line is not checked to see if it is a user-defined 
command. 

9. If a command has not been identified after all the above steps have 
been tried, then it is reported as an unrecognizable command. The 
error message is: 

7KM0N-F -Unrecognizable command 
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The following list summarizes the sequence of events which occur in the 
processing of keyboard commands . If a command can be recognized at any of 
these steps, then the appropriate command is executed and the remaining steps 
are skipped. 

Call user command interface if one is active. 

If command begins with "@", execute command file on DK: . 

If UCL FIRST, check for user-defined command. 

Check for system command. 

If UCL MIDDLE, check for user-defined command. 

Check for command file on DK:. 

Check for command file on SY: . 

Check for SAV file on SY:. 

If UCL LAST, check for user-defined command. 

Report unrecognizable command. 

If user-defined command support has not been included in TSGEN, or if the SET 
UCL NONE command has been issued, or if a command line begins with the 
underscore character ("_"), then the command interpreter never attempts to 
interpret a command as a user-defined command. Attempts to issue user-defined 
commands under these conditions will also be reported as unrecognizable 
commands. 

Examples: 



2. Run a program named "DUMP" on device "SY:". 
.R DUMP 

3. Run a program named "PAYROL" on device "DX1:". 
. RUN DX1: PAYROL 

4. List all files on "RK1:" 
. DIR RK1: 

5. Start a command file "SY: L0ADIT.COM" and pass it the parameter string 
"PR0G2". 

.LOADIT PR0G2 



6. Execute the program "SY: PIP. SAV" and pass it the input line 
"A.TMP=B.TMP". 

.PIP A.TMP=B.TMP 



-19- 



Keyboard Commands 

2.2 User-defined Commands 

It is possible to define your own keyboard commands in terms of system commands 
and other keyboard commands. New keyboard commands may be defined according to 
the following syntax: 

name :== string 

where "name" is a 1 to 11 character command keyword which may consist of 
letters, digits, and the underscore symbol ("_"), and "string" is a string of 
up to 80 characters which defines the body of the command. 

For example, the following command would define the keyword "NOW" as being 
equivalent to the TIME command: 

NOW :== TIME 

Multiple commands may be included in the body of a command definition by 
separating them with the backslash character ("\"). For example: 

NOW :== DATE\TIME 

An up-arrow character ("~") may be included in the command body to cause all 

text on the command line following the command keyword to be inserted in the 

command body at the position of the up-arrow. For example, if a command is 
defined as follows: 

NAMES :== DIR/0RDER:NAME ~ 
Then, if this command is invoked by typing: 

NAMES *.MAC 
The resulting command will be equivalent to: 

DIR/0RDER:NAME *.MAC 

More than one up-arrow character may occur in the command body. The parameter 
string specified when the command is invoked is substituted for each occurrence 
of the up-arrow character. 

A user defined command may invoke other user-defined commands within its 
definition provided that the definition does not call on itself and provided 
that the other commands are defined at the time the command is issued. For 
example, the following command definitions would be legal: 

NOW :== SHOW DATE\SH0W TIME 
STATUS :== N0W\SYSTAT 
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But, the following pair of commands would cause an infinite loop: 

ONE :== TWO 
TWO :== ONE 

It is possible to allow abbreviation of user-defined commands. To do this, 
place an asterisk character ("*") within the keyword at the point of the 
minimum length abbreviation. For example, the definition: 

ST*ATUS :== NOW\SYSTAT 

Would allow the STATUS command to be abbreviated to "STAT" or "ST" but not to 
M S". 

You can specify the order in which the TSX-Plus command interpreter checks for 
user-defined commands by use of the SET UCL command. This command has four 
forms: 

SET UCL FIRST 
SET UCL MIDDLE 
SET UCL LAST 
SET UCL NONE 

If the SET UCL FIRST command is used, user-defined commands will be processed 
before system commands. This allows user-defined commands to replace system 
commands but makes the processing of system commands slower. This is the 
required setting only if it is necessary to replace some system commands. 

If the SET UCL MIDDLE command is used, user-defined commands are processed 
after system commands but before checking for command files and SAV files with 
names that match the command keyword. Using this setting, it is not possible 
to replace a system command with a user command, but both system commands and 
user-defined commands are processed relatively quickly. This is the recom- 
mended setting unless it is desirable to replace system commands. 

If the SET UCL LAST command is used, a command will not be checked to see if it 
is a user-defined command until after it is checked to see if it is a system 
command, the name of a command file on DK, the name of a command file on SY, or 
the name of a SAV file on SY. Using this setting, it is not possible to 
replace a system command with a user command and user commands cannot have the 
same name as command files or SAV files. System commands are processed quickly 
(the same speed as SET UCL MIDDLE), but the processing of user-defined commands 
is slow. This is the appropriate setting only if user-defined commands are 
desired, but command files already exist whose names would conflict with 
user-defined commands. Existing command files which are short and merely 
execute system commands should be replaced by user-defined commands. 

If the SET UCL NONE command is used, user defined commands are never inter- 
preted. In this mode, attempts to invoke user-defined commands will result in 
the error: 
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?KMON-F-Unrecogiiizable command 

The following list illustrates where the FIRST/MIDDLE/LAST setting causes the 
command interpreter to check for and process user-defined commands: 



FIRST — > 
MIDDLE — > 

LAST — > 



See if command is a system command 

Look for command file on DK: with command name 
Look for command file on SY: with command name 
Look for SAV file on SY: with command name 



See the beginning of this chapter for further information on the command 
interpretation process. 

If an underscore character ("__") is typed in front of a keyboard command, this 
is a signal to the system that the command is not to be interpreted as a 
user-defined command. For example, if the NOW command has been defined as 
shown above, then the following command will be recognized as a user-defined 
command and will cause the date and time to be displayed: 

NOW 

However, the following command would not be recognized as a user-defined 
command and would be rejected as an undefined command since there is no NOW 
command defined by the system (unless there is a command file or SAV file on 
SY: with the name NOW): 

NOW 

There are two reasons for using the underscore prefix. If UCL has been set 
FIRST, the underscore prefix can be used to speed up the processing of large 
numbers of system commands that could be present in frequently executed command 
files. For example, the NOW command could be defined as follows to cause it to 
execute faster: 

NOW :== DATE\ TIME 

The second and more important reason for using the underscore prefix is to 
allow user-defined commands to be defined which replace system commands but use 
the system commands in their definitions. (Note that it is necessary to SET 
UCL FIRST to allow system command replacement.) For example, the following 
definition replaces the system DIRECTORY command with a user-defined command 
that has the same name but which always orders the files alphabetically: 

DIR*ECTORY :== DIR/ORDER:NAME ~ 
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If the body of this command were not preceded with the underscore character, 
then it would be a circular definition and cause a futile loop. 

A user-defined command can cause a command file to be executed. However the 
command file invocation must be the last (or only) command defined within the 
body of the command. For example, the following definition causes all BAK 
files to be deleted, and a command file named LOGOFF to be executed when the 
OFF command is used (the LOGOFF command file could end with an " OFF" command 
to do the actual logoff): 

OFF :== DEL *.BAK/NOQ\@LOGOFF 

A user-defined command may be replaced at any time by simply entering a new 
definition for the command. A command may be deleted by entering its name and 
":==" without a command body. For example, the following command deletes the 
definition of the NOW command: 

NOW :»= 

The SHOW COMMANDS keyboard command may be used to display a list of all current 
user-defined commands. 

Commands defined by one time-sharing user are "local" to that user and do not 
affect other users. However, when a virtual line is started the virtual line 
"inherits" the user-defined commands that are in effect for the primary line at 
the time that the virtual line is started. User-defined commands created while 
on a virtual line are not available from other virtual lines or from the 
primary line. All user-defined commands for a job are reset (forgotten) when 
the job logs off. 

The system manager must enable user-defined commands by setting the U$CL flag 
in TSGEN and the program TSXUCL.SAV must be on SY: in order to process 
user-defined commands. The maximum number of commands which can be defined by 
any job is set by the UCLMNC command in TSGEN. The default order for inter- 
pretation of user-defined commands during command processing is determined by 
the TSGEN parameter UCLORD. This may be overridden by the keyboard command SET 
UCL {FIRST | MIDDLE | LAST | NONE} for individual jobs. 
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2.3 User Command Interface 

The User Command Interface (UCI) allows a user-provided program to take over 
the job of command acquisition from the TSX-Plus keyboard monitor. When UCI is 
enabled, the user-written program will be called by the TSX-Plus keyboard 
monitor each time it is ready to accept a new command. It is then the 
responsibility of the user-written program to prompt for a command and accept 
it from the terminal. The program may then perform the appropriate actions, 
chain to other programs or pass commands on to the keyboard monitor. This 
provides a mechanism for such applications as a command menu. 

UCI is enabled with the command: 

SET KMON UCI[=filnam] 

which may be entered either from the keyboard or in a start-up command file. 
If the optional "=filnam" is omitted, then the keyboard monitor passes command 
control to the program SYrUKMON.SAV. This is appropriate when a common command 
interface is desired for multiple lines. If different command interfaces are 
desired for different lines, then the file name of the appropriate user-written 
command interface may be specified. 

After UCI is enabled, the TSX-Plus keyboard monitor will run the user-written 
UCI program each time it needs a new command. The program must prompt the user 
for a new command, accept the command, process it as desired and may optionally 
pass the command to the TSX-Plus keyboard monitor by doing a "special chain 
exit". A special chain exit is performed by issuing the .EXIT request with bit 
5 (mask 40) set in the job status word and with R0 cleared. Any commands to be 
executed by the keyboard monitor are passed through the chain data area. See 
the RT-11 Programmer's Reference Manual for more information on "special chain 
exits". Commands passed to the TSX-Plus keyboard monitor in this fashion 
behave as though the keyboard monitor obtained them from a command file. A 
command file name may also be passed to the keyboard monitor by passing a 
command of the form "@name". If a command file name is passed to the keyboard 
monitor, then it must be the last or only command passed in the chain data 
area. When a command file name is passed in this manner, then all of the 
commands included in the command file are executed by the keyboard monitor 
before returning to the user-written UCI program for another command. 

Keyboard command control may be returned to the TSX-Plus keyboard monitor by 
the command: 

SET KMON SYSTEM 

The following program provides a simple example of the techniques for writing a 
User Command Interface program. This program accepts a command from the 
keyboard and passes It through to the TSX-Plus keyboard monitor if it is a 
legal command. 
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Example: 



.TITLE MYKMON 
.ENABL LC 

Simple example of User Command Interface 

Refuses to pass SET KMON SYSTEM, but otherwise does nothing but 

pass commands thru to KMON. 

.MCALL .PRINT, .EXIT, .GTLIN, .SCCA 



JSW 

SPXIT$ 
MONPTR 
SYSGEN 

BEL 

BS 

LF 

FF 

CR 

ESC 



START: 



1$: 



2$: 



QUIT: 



= 44 
= 40 
= 54 
= 372 

= 7 
= 10 
= 12 
= 14 
= 15 
= 33 

.DSABL 

.SCCA 

MOV 

TST 

BPL 

MOV 

EMT 

ASL 

CMP 

BLOS 

CLR 

MOV 

.PRINT 

.PRINT 

MOV 

EMT 

.PRINT 

.GTLIN 

CALL 

BCS 

MOV 

CALL 

BIS 

CLR 

.EXIT 



GBL 

//AREA, #TTS TAT 

JL-%£f\HVT\mT\ T\ f\ 

^ttMuiNplK.,K.VJ 

SYSGEN(RO) 

QUIT 

#TTYPE,R0 

375 

RO 

R0,#4 

1 6 

RO 

R0,R1 

CLRSCR(Rl) 

//MENU 

#SETRUB,R0 

375 

CENTER(Rl) 

//BUFFER, //PROMPT 

MATCH 

2$ 

#1000, SP 

MOVCMD 

#SPXIT$,@#JSW 

RO 



;Job status word address 

; Special exit flag to pass command to KMON 

; Pointer to base of RMON 

;Offset into RMON of SYSGEN options word 

ASCII bell 
ASCII backspace 
ASCII line feed 
ASCII form feed 
ASCII carriage return 
ASCII escape 

Disable undefined globals 

Inhibit control-C abort 

Get pointer to base of RMON 

Are we running under TSX? 

Normal exit if not 

Point to EMT arg block to 

Get TSX-Plus terminal type 

Convert to word offset 

Legal types are unknown, VT52 and VT100 

If not VT52 or VT100, make unknown 

Save terminal type 

Clear the screen 

Display simple menu 

Point to EMT arg block to 

Set rubout filler character 

Move to screen center and clear the line 

Accept input line 

See if it's legal 

Repeat if illegal command 

Ensure stack pointer safe 

Move command from buffer to chain data area 

Set special chain exit bit in JSW 

Required for special chain exit 

And pass command to KMON 



Simple matching. Easy to defeat by inserting extra spaces! ! ! 
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MATCH 


MOV 


//BUFFER, R2 




MOV 


#ILLCMD,R3 


1$: 


TSTB 


<R2) 




BEQ 


2$ 




CMPB 


(R2)+,(R3)+ 




BNE 


9$ 




CMP 


R3,#ILLEND 




BLO 


1$ 


2$: 


SEC 






BR 


10$ 


9$: 


CLC 




10$: 


RETURN 





; Point to beginning of input buffer 

; Point to beginning of illegal command 

;At end of input string? 

;Yes, matched so far, probably illegal 

;No, test through end of illegal string 

;No match, not illegal command 

;Past end of illegal command? 

;No, keep checking 

;Strings match, signal illegal command 

; Strings don't match, signal legal command 



Move command from input buffer to chain data area. 



MOVCMD: MOV 
MOV 



1$: 



2$: 



3$: 



9$: 



MOVB 

BNE 

CLRB 

BR 

CMPB 

BNE 

CLRB 

MOVB 

CMP 

BLO 

CLRB 

SUB 

MOV 

RETURN 



//BUFFER, R2 

#512, R3 

(R2)+,R0 

2$ 

(R3)+ 

9$ 

ro,#-\ 

3$ 

R0 

R0,(R3)+ 

R2,//BUFEND 

1$ 
-1(R3) 

#512, R3 
R3,@#510 



Point to beginning of input string 

Point to chain data area 

Get next char 

Continue if not nul 

If end of input command 

then done 
Command separator? 
No, move it 
Yes, replace with nul 
Move command into chain data area 
Don't want to overflow 
Keep moving if characters left 
Mark end of command (ensure it is ASCIZ) 
How many bytes did we move? 
Mark the number for .CHAIN 



AREA: .BLKW 10 ;GP EMT argument area 

TTSTAT: .WORD ; Terminal status word for .SCCA 

TTYPE: .BYTE 0,137 ;EMT arg block to get terminal type 

SETRUB: .BYTE 0,152 ;EMT arg block to control terminal funtions 

.WORD A ;Function code - set rubout filler 

.WORD ;Rubout filler = underline 

CLRSCR: .WORD CLRUNK,CLR52,CLR100 ;Terminal specific screen clears 

CENTER: .WORD CNTUNK,CNT52,CNT100 ;Terminal specific move and clear 

.NLIST BEX 

CLRUNK: .BYTE FF,FF,FF,CR,200 ;Emulate clear screen with 3*(8LFs) 

CLR52: .BYTE ESC, 'H, ESC, 'J, 200 ;VT52 clear screen sequence 

CLR100: .ASCII <ESC>/[H/<ESC>/[ J/<200> ;VT100 clear screen sequence 

CNTUNK: .ASCII <CRXLFXLFXLF>/ /<200> 

CNT52: .ASCII <ESC>/Y% / ;Line 6, column 1 

.ASCII <ESO/K/ ;Erase to end of line 

.ASCII / /<200> ;Move to column 6 

CNT100: .ASCII <ESC>/[6;6f/ ;Line 6, column 6 
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.ASCII <ESO/[2K/<200> ;Erase entire line 

MENU: .ASCII <LFXLFXLF>/ ***** Simple Menu *****/<200> 

PROMPT: .ASCII <BEL>/ Command: / 

.NLIST 

.REPT 32. 

.BYTE BS ;Backspace to beginning of field 

.ENDR 

.LIST 

.BYTE <200> ;End of string 

ILLCMD: .ASCII /SET KMON SYSTEM/ ;Don't permit UCI disable 
ILLEND: 

BUFFER: .BLKB 81. ;Command line input buffer 

BUFEND: 

.END START 
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2.4 Keyboard Commands 

The keyboard commands accepted by TSX-Plus are listed below. Because many 
commands are identical or very similar to those of RT-11, full descriptions are 
only provided for TSX-Plus specific commands and for differences between 
TSX-Plus and RT-11 commands. Users should consult the RT-11 System User's 
Guide for more information on keyboard commands. 



The ACCESS Command 

The ACCESS command is used to restrict user access to a particular set of files 
or devices. It is only valid in start-up command files. Refer to the TSX-Plus 
System Manager's Guide for further information about this command. 



The ASSIGN Command 

The ASSIGN command is used to associate a logical I/O device name with a 
physical device. To simply assign a logical device name to a physical device, 
the form of the ASSIGN command is the same as that under RT-11. For example, 
to assign the logical device name "BIN" to physical device "DX1" the command 
would be: 

ASSIGN DX1 BIN 

The following command would assign logical device "BIN" to a file named "PR0G1" 
on the system device: 

ASSIGN SY:PR0G1=BIN 

It is also possible under TSX-Plus to assign a new logical name to a previously 
assigned logical name. The effect is to assign the new logical name to the 
same physical device to which the previous assign was directed. For example, 
the following sequence of ASSIGNS result in both logical devices "AA" and "BB" 
being assigned to "DLl". 

ASSIGN DLl AA 
ASSIGN AA BB 

The ASSIGN command is frequently used to assign FORTRAN I/O unit numbers to 
selected devices. To assign FORTRAN I/O unit number 1 to the terminal, the 
command would be: 

ASSIGN TT 1 

The TSX-Plus ASSIGN command provides a useful extension. In addition to being 
able to specify a physical device name, the user may specify a file name, 
extension, and size. If a file name and optional size are specified in 
addition to the physical device name, the file name and size follow the device 
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name. For example, the following command assigns FORTRAN I/O unit number 1 to 
a file named "PAYROL" on device "BXO" with a size of 43 blocks: 

ASSIGN DXO: PAYROL [43] =1 

A maximum of fifteen assignments may be in effect at any given time for each 
user. 



The BACKUP Command 

The TSX-Plus BACKUP command has the same form and options as the RT-11 BACKUP 

command. 



The BOOT Command 

The BOOT command attempts to abort TSX-Plus and reboot RT-11. Due to the 
variations in hardware and bootstrap ROMs, this command is unsupported. The 
BOOT command may either reboot RT-11 on your system or simply halt depending on 
your particular hardware configuration. Unlike the RT-11 BOOT command, no 
device or file name may be specified with the TSX-Plus boot command; BOOT 
always attempts to reboot from the system (SY) device. Operator command 
privilege is required to use this command. The BOOT command is equivalent to 
the $STOP command. 



The BYE Command 

The BYE command is used to log off a timesharing line. It is equivalent to the 

OFF command. 



The COBOL Command 

The COBOL command is used to compile a COBOL source program using the COBOL- 
Plus compiler. COBOL-Plus, a product of S&H Computer Systems, Inc., is sold 
separately. The default extension for COBOL source programs is "CBL"; the 
default extension for COBOL object files is "CBJ". The COMPILE, LINK and 
EXECUTE commands may also be used to compile and execute COBOL programs. 
TSX-Plus will implicitly invoke the COBOL-Plus compiler and CBLINK link program 
if the source program has the extension "CBL" or the object program has the 
extension "CBJ". Switches that can be used with the COBOL command are listed 
below. 
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Switch 



/ALLOCATE: size 

/ANSI 

/CARD 

/CREF 

/CROSS 

/DCARDS 

/INFORMATION 

/LINENUMBER 

/LIST [-.name] 

/NARROW 

/OBJECT[:name] 

/ONDEBUG 

/PRODUCTION 

/RM 

/SEQUENCE 

/SUMMARY 

/WARN 



Meaning 

Specify size of list or object file. 

Produce warning messages for non-ANSI feature use 

Source program is in card sequence format. 

(Equivalent to /CROSS). 

Produce a cross-reference of the source program. 

Compile lines with "D" in the indicator field. 

Print additional information at compilation end. 

Enable source line information in object listing. 

Produce a source program listing. 

Format the cross-reference for 80 column display. 

Specify name of object file. 

Compile the program for use with the debugger. 

Omit line number tracing and subscript checking. 

Compile RM/C0B0L(*) programs. 

(Equivalent to /CARD). 

Print only error messages on listing device. 

Suppress warning messages. 



See the COBOL-Plus reference manual for further information about the COBOL 
command. 

* RM/C0B0L is a trademark of Ryan-McFarland Corporation. 



The COMPILE Command 

The COMPILE command invokes the appropriate language processor to compile the 
specified source file. The TSX-Plus COMPILE command is the same as the RT-11 
COMPILE command except that it also recognizes programs with the extension 
"CBL" as COBOL source programs and calls the COBOL-Plus compiler. When 
compiling a COBOL program, the switches that are legal with the COBOL command 
may also be used with the COMPILE command. It is also possible to explicitly 
specify that the COBOL-Plus compiler is to be called by using the "/COBOL" 
switch with the COMPILE command. The default compiler for files with the 
extension "DBL" is DBL; this may be changed with the SET LANGUAGE command. 



The COPY Command 

The TSX-Plus COPY command has the same form and options as the RT-11 COPY 

command. 



The CREATE Command 

The TSX-Plus CREATE command has the same form and options as the RT-11 CREATE 

command. 
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The DATE Command 

The TSX-Plus DATE command has the same form and options as the RT-11 DATE 

command. Operator privilege is required to set the date. 



The DEASSIGN Command 

The TSX-Plus DEASSIGN command is equivalent to the RT-11 DEASSIGN command. It 

is used to dissociate a logical unit assignment. 



The DELETE Command 

The TSX-Plus DELETE command has the same form and options as the RT-11 DELETE 

command. 



The DETACH Command 



The DETACH command is used to initiate execution of a command file as a 
"detached" job, to abort a detached job or to check the status of a detached 
job. The system manager may restrict the use of this command. 

The form of the command used to start a detached job is: 



where "file" is the name of a command file which is to be started as a detached 
job. If a free detached- job line is available, the system starts, the command 
file and prints a message indicating the detached job line number used. 
Detached- job lines must be declared when TSX-Plus is generated. The DETACH 
command itself and detached command files do not inherit any logical device 

ctssj-glwicuu » • 11 no Qcvilc name xS spccnicu in L-iic jJ.Ei j. .nv.fi uOuuIicinu, unc cuuimauu 

file is assumed to be on the system device (SY:). 

In the following example a command file named "CRUNCH" is started as a detached 
job. 

. DETACH CRUNCH 

Job started on line #5 

If the specified command file is not found, the start message will still 
appear, but the job is not actually started. Any error message would have been 
sent to the detached line, but is ignored since terminal output is not sent to 
detached jobs. With no input, the detached job then aborts. The result is 

that the detached job is not started and no warning appears* 

Terminal output for detached jobs is normally discarded since they are not 
attached to any terminal. However, it is possible to collect the terminal 
output from a detached job by sending it to a log file. This can be done by 
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using the SET LOG FILE=filnam command in the detached job command file. See 
the SET LOG command for more information on terminal output logging. 

The form of the DETACH command used to abort a detached job is: 

DETACH/KILL line-number 

where "line-number" is the number of the line assigned to the detached job. 

The form of the DETACH command used to check the status of a detached job line 
is: 

DETACH/CHECK line-number 

In response to this command, TSX-Plus will indicate whether a job is still 
executing on the line. 

See Chapter 4 for more information about detached jobs. 



The DIBOL Command 

The DIBOL command is used to compile a DIBOL source program. The default 
compiler for programs with the extension "DBL" is DBL. This may be changed 
with the SET LANGUAGE command. The TSX-Plus DIBOL command has the same form 
and options as the RT-11 DIBOL command, except that the options /BUFFERING, 
/LOG, /PAGE and /TABLES are not supported. Because of differences between 
compiler switch options, DIBOL switches are not supported for use with DBL. 



The DIFFERENCES Command 

The DIFFERENCES command is used to compare two files. The TSX-Plus DIFFERENCES 

command has the same form and options as the RT-11 DIFFERENCES command. 



The DIRECTORY Command 

The TSX-Plus DIRECTORY command has the same form and options as the RT-11 

DIRECTORY command. 
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The DISMOUNT Command 

The DISMOUNT command has three functions: 1) it tells TSX-Plus to stop 
directory caching on a particular device; 2) it tells the system to stop doing 
data caching on a device; 3) it dissociates a logical subset disk from its 
assigned file. The form of the DISMOUNT command is: 

DISMOUNT ddn 

where "ddn" is the real or logically assigned name of the device. 

If the device is a physical device or a logical name for a physical device, 
then the DISMOUNT command removes the current job's entry from the mount table 
for that device. If no other jobs have mounted the device, then directory and 
data caching for that device are stopped. Files on a physical device may still 
be accessed after it is DISMOUNTed, but access may be slower since the 
directory is no longer cached. Note however, that if a job accesses a device 
which it has not mounted, and another user INITIALIZES or SQUEEZES that device, 
then reads will probably return garbage and writes will probably corrupt other 



nies . 
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The INITIALIZE and SQUEEZE operations cannot be performed on a device which is 
mounted by other users. If it is necessary to INITIALIZE or SQUEEZE a device 
which is mounted by other users, then they must first DISMOUNT that device. 
Remember that it is possible for a job which has not mounted a device to still 
access that device. After a device is INITIALIZEd or SQUEEZEd, then the 
director^ 7 and data caches are cleared for that device and if it is still 
mounted, then caching is resumed. Caching is not resumed if all jobs have 
DISMOUNTed a device until some job reMOUNTs that device. The following 
information message is printed if a device is dismounted and the device is 
still mounted by other users: 

?KMON-I-Device is still mounted by other users 

The SHOW MOUNTS command may be used to determine which jobs have devices 
mounted . 

In the case of logical subset disk assignments ("ddn" = LD0-LD7 or logical 
names assigned to them), the effect of the DISMOUNT command is to stop 
directory caching on the logical subset disk as described above and to remove 
the device from the logical subset disk tables. In this case, files on the 
logical subset disk are no longer accessible until the logical subset disk is 
re-mounted. This form of the command only affects the logical subset disks 
belonging to the user who issues the command. If another job has mounted the 
same logical subset disk, then the rules for physical devices with regard to 
INITIALIZE and SQUEEZE also apply to the logical subset disk. 
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The DISPLAY Command 

The DISPLAY command is used within a command file or user-defined command to 

cause a line of text to be displayed on the terminal when the command is 

executed. This is useful in command files that are not being listed to keep 

track of progress through the command file. The form of the DISPLAY command 

is: 

DISPLAY comments 

where "comments" can be any text string to be displayed on the terminal. See 
the section on user-defined commands in this chapter and Chapter 3 for more 
information on command files. 



The DUMP Command 

The TSX-Plus DUMP command has the same form and options as the RT-11 DUMP 

command. 



The EDIT Command 

The TSX-Plus EDIT command has the same form and options as the RT-11 EDIT 

command. 



The EXECUTE Command 

The TSX-Plus EXECUTE command has the same form and options as the RT-11 EXECUTE 
command. It also recognizes programs with the extension "CBL" as COBOL source 
programs and automatically invokes the COBOL-Plus compiler and linker. 
Switches appropriate when using the COBOL-Plus compiler and linker are also 
valid with EXECUTE. See also the COBOL, COMPILE, DIBOL, FORTRAN, LINK and 
MACRO commands. 



The FORM Command 

The FORM command is used to specify the default form name for subsequent files 

sent to the spooler by the user. The form of the FORM command is: 

FORM name 

where "name" is the one to six character default form name to be used for all 
files sent to the spooler until another FORM command is issued. The initial 
default form name is "STD". A form may also be requested within a file sent to 
the spooler. See Chapter 5 for more information on spooled devices and forms. 
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In the following example a FORTRAN listing will be generated for printing on a 
form called "2-PART". 

. FORM 2 -PART 
. COMPILE/LIST TEST. FOR 
.FORM STD 



The FORTRAN Command 

The TSX-Plus FORTRAN command has the same form and options as the RT-11 FORTRAN 

command. 



The HELP Command 

The TSX-Plus HELP command has the same form and options as the RT-11 HELP 

command. 



The INITIALIZE Command 

The TSX-Plus INITIALIZE command has the same form and options as the RT-11 
INITIALIZE command. However, the system device (booted device when TSX-Plus is 
started) may not be initialized when running TSX-Plus. If it is necessary to 
initialize the system device, it must be done under RT-11. The resulting error 
message is : 

?KMON-F-This operation not legal with SY (system) device 

A device cannot be initialized if any other user has MOUNTed the device. 
Attempts to INITIALIZE a device which is mounted by another user will result in 
the error message: 

?KMON-F -Device is mounted by another user 

If the device is only mounted by the job which initializes it, then the 
directory and data caches are cleared after the operation and caching is 
resumed. The SHOW MOUNTS command may be used to determine which other users 
have mounted a device. However, remember that is still possible for a job 
which has not mounted a device to access that device. If such a job has a file 
open before you initialize, then severe problems can arise. Great circum- 
spection is necessary before initializing a device in a multi-user environment. 
Do not initialize rashly. As a defensive measure, always MOUNT any disk device 
which you plan to use. 
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If terminal output logging is being done (see the SET LOG command) and the log 
file is open on the device being initialized, then the log file is closed 
before the device is initialized and the following warning message appears: 

?KMON-W-Closing log file 



The KILL Command 

The KILL command is used to abort a timesharing job on another line. This has 
the effect of aborting the execution of the job and forcing the logoff of the 
line. Operator command privilege is required to use the KILL command. The 
form of this command is: 

KILL line-number 
where "line-number" is the number of the job to be killed. 



The KJOB Command 

The KJOB command is used to log off a timesharing line. It is equivalent to 

the OFF command. 



The LIBRARY Command 

The TSX-Plus LIBRARY command has the same form and options as the RT-11 LIBRARY 
command. It also can be used to build COBOL-Plus object program libraries; see 
the COBOL-Plus Reference Manual for further information. 



The LINK Command 

The TSX-Plus LINK command has the same form and options as the RT-11 LINK 
command. It also recognizes object files with the extension "CBJ" as COBOL- 
Plus object files and then invokes the COBOL-Plus link program (CBLINK). The 
COBOL-Plus linker may also be explicitly specified with the "/COBOL" switch. 
See the COBOL-Plus Reference Manual for further information. Switches which 
are unique to COBOL Plus - are: 

Switch Meaning 



/NOPAGE Do not swap data segments. 

/NOSHARED Do not use shared COBOL-Plus run-time library. 

/SHARED Always use shared COBOL-Plus run-time library. 

/SIZE Report the size of the largest data segment. 

/VM Use VM for run-time and program segmentation. 

/XM Load entire program and run-time into extended memory, 
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The MACRO Command 

The TSX-Plus MACRO command has the same form and options as the RT-il MACRO 

command. 

The MAKE Command 

The MAKE command is used to create a new file with the TECO editor. It is 

equivalent to the RT-11 MAKE command. 

The MEMORY Command 

The MEMORY command is used^to control the amount of memory available to a job. 
When a job initially "logs on" it receives a default memory allocation set by 
the system manager. The MEMORY command can be used to change the allocation 
for the job. The form of the MEMORY command is: 

MEMORY nn 

Where "nn" is the number of k-bytes (Kb, 1024. bytes) of memory to be allocated 
for the job. The maximum memory size that a job may use is set by the system 
manager, but never exceeds 64Kb. When a running program performs a .SETTOP EMT 
the top of memory address corresponds to the size last specified by a MEMORY 
command. Note that .SETTOP EMT's do not actually affect the amount of memory 
allocated to a job — only the MEMORY command and a TSX-Plus EMT described in 
Chapter 7 do that. 

Programs are only allowed to use more than 56Kb of memory if they are 
"virtual", meaning they do not directly access the RMON area, although they may 
access it indirectly by use of the .GVAL and .PVAL EMT's. Programs may 
indicate that they are virtual by any of the following techniques: 

1. Set bit 10 (mask 2000) in the job status word (location 44) of the 
SAV file. See Appendix A for information about how the SETSIZ 
program can be used to do this. 

2. Use the /V LINK switch (/XM switch for the LINK keyboard command) 
which stores the RAD50 value for "VIR" in location of the SAV file. 

3. Store a memory allocation size greater than 56Kb in location 56 of 
the SAV file. See Appendix A for information about how the SETSIZ 
program can do this. 

If none of these conditions is met the program is restricted to 56Kb even if a 

larger value is specified with the MEMORY command. 

See Chapter 8 and Appendix A for more information on memory usage and virtual 
image s . 



-37- 



Keyboard Commands 

A program may dynamically control the amount of memory allocated for the job by 
use of the TSX-Plus EMT with function code 141 (described in Chapter 7). See 
also the description of the SETSIZ program in Appendix A for information about 
how the amount of memory to be allocated for a particular program can be stored 
in the SAV file for the program. 

If the MEMORY command is entered without specifying a size, the current and 
maximum memory allocation for the job is displayed. See also the description 
of the SHOW MEMORY command. 



The MONITOR Command 

The MONITOR command is used to cause TSX-Plus to begin a performance analysis. 
See Chapter 13 for complete information about the TSX-Plus performance analysis 
feature. The form of the MONITOR command is: 

MONITOR base-address, top-address [ ,cell-size] /switches 

where "base-address" is the lowest address in the program region being 
monitored, "top-address" is the highest address in the region, and "cell-size" 
is the number of bytes to group per histogram cell. The only valid switch is 
"/I" which causes I/O wait time to be included in the analysis. 



The MOUNT Command . 

The MOUNT command is used to: 1) begin directory caching on a file-structured 
device; 2) enable data caching on a device; and 3) associate a logical subset 
disk with a disk file. 

Directory caching is a technique that speeds up file "lookups" by keeping 
information about files in memory so that it is not necessary to access the 
directory on the device each time a file is opened. Data caching is a 
technique used to speed up disk reads by keeping memory resident copies of 
recently used file blocks. Both directory and data caching are enabled during 
TSX-Plus system generation and activated when a device is MOUNTed. The form of 
the MOUNT command to activate directory and data caching is: 

MOUNT ddn 

where "ddn" is a physical device name such as "DL1:". The effect of this type 
of MOUNT command is to tell TSX-Plus that it should begin directory and data 
caching for the device being mounted. The system device is automatically 
MOUNTed for each user. If caching is not wanted, then no MOUNT should be 
performed, or the DISMOUNT command should be used to halt caching on a 
previously mounted disk. 
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The INITIALIZE and SQUEEZE operations cannot be performed on a device which is 
mounted by other users. If it is necessary to INITIALIZE or SQUEEZE a device 
which is mounted by other users, then they must first DISMOUNT that device. 
Remember that it is possible for a job which has not mounted a device to still 
access that device. 

Once a MOUNT command is issued, caching is enabled for all users who access 
files on the device (including users who have not MOUNTed the device). The 
system maintains a table of all users who have mounted each device. See also 
the DISMOUNT and SHOW MOUNTS commands. 

Warning ; If directory caching is enabled for a device, it is crucially 
important that the DISMOUNT command be used to dismount the device before a 
disk is replaced on the same drive. If a new disk pack is inserted in the 
drive without issuing the DISMOUNT command, TSX-Plus would try to access files 
on the new pack according to the locations stored in the directory cache for 
the old pack. 

Directory caching causes a dramatic improvement in the speed of file "lookups" 
but does not speed up file "enters", "deletes" or "renames". This is because 
TSX-Plus always updates the directory on the device when it is altered. The 
maximum number of devices whose directories may be cached and the number of 
file entries that are kept in the directory cache are specified when TSX-Plus 
is generated. 

The second form of the MOUNT command is used to associate a logical subset disk 
with a disk file. The form of the command is: 

MOUNT [/ [NO ] WRITE] LDn filnam [logical-name] 

where "LDn" is the logical subset disk, and n is in the range 0-7, "filnam" is 
the name of a disk file containing the subset files, and "logical-name" is an 
optional logical name to be assigned to the logical subset disk. The [NOjWRITE 
option controls access to the logical subset disk. WRITE allows full access, 
whereas NOWRITE allows read-only access. WRITE access is allowed by default 
unless the NOWRITE option is used. The default extension for the disk file to 
be associated with a logical subset disk is "DSK". File protection is 
automatically set on the file specified to be a logical subset disk. When a 
logical subset disk is mounted, directory and data caching are also begun for 
it. 

Each user may mount up to 8 logical subset disks at any time. The association 
between a logical subset disk (LD0-LD7) and a file is "local" to each user. 
For example, one user may associate LD2 with file DL1:MYDISK.DSK while another 
user associates LD2 with file DL1:Y0RDSK.DSK. 

Logical subset disks may be "nested", allowing one or more subsets to be 
defined within other subsets. However, if this is done, the MOUNT commands 
must be executed sequentially from outer-most to inner-most logical subset disk 
and the unit numbers must be assigned sequentially from LDO to LD7. 

-39- 



Keyboard Commands 

Example : 

. MOUNT LDO MANUAL MAN 

. CREATE LDO : SUB . DSK7aLLOCATE : 100 . 

. MOUNT/WRITE LD2 MAN: SUB 

. INIT/NOQ LD2: 

Other commands which refer to logical subset disks are: DISMOUNT, SET LDn 
{CLEAN|WRITE|NOWRITE} and SHOW SUBSETS. The ACCESS command may also be used 
with logical subset disks in start-up command files. The restrictions on 
INITIALIZE and SQUEEZE operations also apply when another user has mounted the 
same logical subset disk. 

Logical subset disk support is integral to the file management functions of 
TSX-Plus, and does not require the "LD" pseudo-device handler. Consequently, 
it is independent of the version of RT-11 supporting TSX-Plus. See Appendix G 
for more information on the use of logical subset disks. 



The MUNG Command 

The MUNG command is used to start a file of TECO commands. The MUNG command is 

equivalent to the RT-11 MUNG command. 



The OFF Command 

The OFF command is used to log off a time-sharing line, and to release a 
virtual line (see the discussion of virtual lines in Chapter 4). The accumu- 
lated connect time and CPU time used during the session are printed during the 
logoff processing. The BYE and KJOB commands are synonyms for the OFF command. 
TSX-Plus automatically logs off dial-up lines if the telephone connection is 
broken. A special log-off command file may also be designated to execute 
whenever a job logs off; see the TSX-Plus System Manager's Guide for more 
information. 

Example: 



.OFF 



Connect time=01: 43:00 CPU=00:12:03 



The OPERATOR Command 

The OPERATOR command is used to send a message to the operator's console. The 

OPERATOR command works like the SEND command, but it is not necessary to know 

the line number of the operator s terminal. The form of the OPERATOR command 

is: 
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OPERATOR message 
For example, to send a disk mount message to the operator: 
. OPERATOR PLEASE MOUNT PAYROLL MASTER DISK ON RK1 

The PAUSE Command 

The PAUSE command is used within command files (see Chapter 3) to temporarily 

suspend processing of the file. The form of the PAUSE command is: 

PAUSE comments 

where "comments" may be any string of characters. When a PAUSE command is 
encountered within a command file, the PAUSE command is printed on the terminal 
followed by "»". Execution of the command file is suspended until carriage 
return is pressed. This gives the operator an opportunity to perform manual 
operations such as mounting disks or tapes. 

The PRINT Command 

The TSX-Plus PRINT command has the same form and options as the RT-11 PRINT 

command. 

The PROTECT Command 

The TSX-Plus PROTECT command has the same form and options as the RT-11 PROTECT 

command. 

The R Command 

The "R" command is used to start a program. The form of the command is: 

R[ /switch] filnam [input-data] 

If no device name is specified with the program name, TSX-Plus attempts to find 
the specified program on "SY:" . The amount of memory available to a program 
can be controlled with the MEMORY command, or size information can be included 
in its disk image. See the description of the SETSIZ program in Appendix A for 
more information about how the amount of memory allocated for a program may be 
controlled. See also Chapter 8 for more information on the operating environ- 
ment for programs under TSX-Plus. 

A line of input may be passed to a program by specifying it as part of the "R" 
command following the program name. If this is done the program will receive 
the text string as its first line of input and will receive control-C as its 
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second line of input. (See example 2 below.) Note that only programs which 
accept input with the .GTLIN, .CSISPC, and .CSIGEN requests can accept input in 
this manner. Single character input (.TTYIN) does not normally accept data 
from a command line; however, the program can be invoked with a command file 
and accept all terminal input from the command file - see the section on 
command file control characters in Chapter 3. Note also that text passed on 
the command line will be reorganized ir it contains multiple words separated by 
spaces. The first word will be placed as the input to a CSI command string and 
the remainder of the line will be placed on the output side of the equal sign. 
(See example 7 below.) 

The valid switches for the R (and RUN) command are: 

/DEBUG — Run program under control of debugger 
/HIGH — Run program in high efficiency TTY mode 

/LOCK — Lock program to line 

/NONINTERACTIVE — Run program in non-interactive mode 
/SINGLECHAR — Run program with single-character activation 

All switches can be abbreviated to a single character. 

The /DEBUG switch causes the program being started to execute under control of 
the TSODT debugging program. Before loading the program, a relocatable copy of 
the TSODT program ("SY: TSODT. REL") is loaded into the upper-most portion of the 
user's available memory space (reducing the memory space available to the 
running program by about 4Kb). The program being started is then loaded into 
the memory space below TSODT and control is passed to TSODT. TSODT responds by 
printing a greeting message and waiting for a command from the terminal. At 
this point register ("$0") contains the address of the starting point of the 
program. TSODT may be used to display or examine locations or set breakpoints 
in the program. The program is started with the TSODT "xxxxxx;G" command 
(where "xxxxxx" is the starting address of the program). The /DEBUG switch 
allows programs run under TSX-Plus to be debugged without special linking with 
a debugging program. Because of the mapping for TSKMON while TSODT is being 
loaded, programs larger than 28Kb must be linked with TSODT for debugging 
rather than use the /DEBUG switch. Commands and functions of TSODT are 
equivalent to those of ODT provided with RT-11. 

The /HIGH switch automatically enables the program to use high efficiency 
terminal I/O. This disables much of the character testing done during terminal 
operations and can increase terminal throughput. See the description of the 
"R" program controlled terminal option in Chapter 6 for more information on 
high efficiency terminal mode. 

The /LOCK switch causes the program that is being started to be "locked" to the 
time-sharing line so that the line is automatically logged off when the program 
exits. If the "R/LOCK" command occurs within a command file the command file 
is terminated as the program is started and any additional information in the 
command file is ignored. The most frequent use of this feature is in start-up 
command files where a line is to be restricted to executing a particular 
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program. If a locked program chains to another program, the program that was 
chained to then becomes the locked program. See example 4 below. 

The /NONINTERACTIVE switch prevents a program from receiving the priority boost 
normally given to jobs on the completion of terminal input. This should be 
used with programs which do heavy terminal I/O but which are not really 
interactive jobs, such as file transfer programs. A program run with this 
switch will execute at a lower priority and will not interfere with interactive 
jobs. The effect of this switch is cleared when a program exits to KMON, but 
the switch remains in effect if the program chains to another program. 

The /SINGLECHAR switch causes a program to execute in "single character 
activation" mode. (See the discussion of activation characters in Chapter 6.) 
Normally when programs are run under TSX-Plus they do not receive terminal 
input until an "activation" character such as carriage-return has been entered. 
This is true even if the program sets bit 12 in the Job Status Word. Also, 
TSX-Plus does not normally allow a program to test for terminal input without 
stalling on the .TTYIN EMT. However, the /SINGLECHAR switch causes TSX-Plus to 
honor bits 6 and 12 of the Job Status Word, allowing the program to activate on 
each character and test for terminal input without stalling. A program can 
also cause TSX-Plus to honor JSW bits 6 and 12 by using the "U" and "S" 
terminal control commands (see Chapter 6). The example program "STEALS" in the 
section on requesting exclusive system control in Chapter 11 uses single 
character activation in this way. KED and K52 are automatically run in single 
character activation mode. 

Examples: 

1. Run the program named "DUMP" on device "SY:". 

.R DUMP 

2. Run the program named "PIP" on "SY:" and pass to it the 
input line "A.TMP=B.TMP. 

. PIP A.TMP=B,TMP 

3. Run the program named "SAMPLE" on "RK2:". 
.R RK2: SAMPLE 

4. Start the execution of BASIC and force logoff on exit. 
. R/LOCK BASIC 

5. Start a program named PLANE and allow it to 
use single character activation mode. 

.R/ SINGLE PLANE 
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6 . Start a program named TRIAL in debug mode so that 
it will be run under TSODT. 

. R/DEBUG TRIAL 
*TSX-0DT-V4* 



7. Start the program SY: GETLIN and pass it some input text 
.R GETLIN INPUT OUTPUT 

The program GETLIN will receive the following text: 
OUTPUT=INPUT 



The RENAME Command 

The TSX-Plus RENAME command has the same form and options as the RT-11 RENAME 

command. 



The RESET Command 

The RESET command is used to reset the system usage statistics that are 
displayed with the SYSTAT command. Data caching statistics are also reset by 
the RESET command. This is useful when you want to monitor system performance 
during a particular part of the day. Operator command privilege is required to 
use the RESET command. The TSX-Plus RESET command is NOT equivalent to the 
RT-11 RESET command. 



The RUN Command 

The RUN command is equivalent to the "R" command except that the default device 
is "DK:" instead of "SY:". See the description of the "R" command for 
information about available switches. 



The SEND Command 

The SEND command is used to send messages between time-sharing terminals. The 

form of the command is: 

SEND [, line//] message 

where "line//" is the number of the line to which the message is to be sent. If 
no line number is specified, the message is broadcast to all logged-on lines. 
Jobs may inhibit the reception of messages while executing programs by using 
the SET TT GAG command. 
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Examples: 

1. Send a message to all logged-on users: 

.SEND- Bob, Call me when you get a. chance . 

2. Send a message to line number 2: 

. SEND, 2 Will you be on tonight? 

When a SEND message is printed at a terminal, the message is preceded by the 
number of the line that originated the message and the user name currently 
associated with that line. For example, a message from line 1 might be printed 
as follows: 

01 (SYSMGR) — Bob, Call me when you get a chance. 

Keep in mind that several characters are used to identify the sending line and 
user, with the result that a long message may be truncated. 



The SET Command 

The SET command is used to set various options controlling system operation. 

The general form of the SET command is: 

SET device option 

As with RT-11, the TSX-Plus SET command is used to specify options .for devices 
such as line-printers and card-readers as well as setting certain system 
parameters such as terminal control characteristics. When used to set device 
options, the SET command has the same form as under RT-11 and may set the same 
options (they are specified in the handler). The SET command causes the copy 
of the device handler on the disk to be altered so that the effect of the 
command becomes "permanent" (until another SET changes the parameter back). 
The SET command also attempts to make the change to the copy of the handler 
that is in memory with TSX-plus. If the handler is idle when the SET is done, 
the change will be made; otherwise, a warning message: 

7KM0N-F -Handler active — Can't update running copy 

will be printed and the running copy of the handler is not altered. When a SET 
is done to a device handler, blocks and 1 of the handler are read from the 
disk, the SET option is applied and then block 1 is written back to the disk 
and moved over the copy of block 1 that is in memory. If the vector of a 
device is changed with the SET dd VECTOR=nnn command, TSX-Plus must be 
restarted to function correctly. Operator command privilege is required to set 
an option in a device handler. See the RT-11 System User's Guide for device 
handler SET options. 
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SET CACHE 

The SET CACHE command is used to alter the number of blocks which may be held 
in the generalized data cache. This command does not alter the amount of 
memory reserved for the data cache, but only controls the number of blocks 
within the limits allowed by the CACHE parameter selected during system 
generation. This command is used by the system manager to determine the effect 
of varying cache sizes on system performance. Operator privilege is necessary 
to use this command. The form of this command is: 

SET CACHE blocks 

where "blocks" may range from to the number of blocks reserved by the CACHE 
parameter during system generation. 



SET CCL 

There are two types of system commands, low level commands such as RUN, SET, 
ASSIGN and high level commands such as EXECUTE, COPY, DELETE, and DIRECTORY. 
Low level commands are executed directly by TSX-Plus. High level commands are 
translated into the appropriate low level commands before execution. The set 
of high level commands is known as the Concise Command Language (CCL). The 
"SET CCL" command can be used to observe the low level commands that are 
produced by translating CCL commands. The form of this command is: 

SET CCL [NOJTEST 

When TSX-Plus is in CCL TEST mode, it will display at the terminal the low 
level commands that are generated by a CCL command, but not execute them. The 
"SET CCL NOTEST" command turns this mode off and TSX-Plus goes back to 
executing CCL commands. Test mode is very useful if you are having trouble 
getting some complex CCL command to work and want to examine the low level 
commands that are being generated. 

Example: 

. SET CCL TEST 

. DIR/OUTPUT:DIR. DAT/OCTAL/BLOCKS DL1: 

R DIR 

DK: DIR.DATHDL1 : * . */0/B 

~C 

.SET CCL NOTEST 
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SET CORTIM 

The SET CORTIM command is used to adjust the value of the CORTIM system control 
parameter. This parameter controls the minimum memory residency time for jobs 
just swapped into memory. See the TSX-Plus System Managers Guide for further 
information about the CORTIM parameter. The form of this command is: 

SET CORTIM value 

where "value" is the time value specified in 0.1 second units. The current 
value of the CORTIM parameter may be determined with the SHOW CORTIM command. 
Operator command privilege is required to use this command. 



SET EDIT 

The SET EDIT command is used to select which edit program will be invoked when 

the system EDIT command is used. The form of this command is: 

SET EDIT option 

where "option" may be EDIT, TECO, KED or K52. The options KED and K52 are 
actually synonymous; the KED editor is used if the terminal type has been 
specified to be a VT100 and the K52 editor is used if the terminal type has 
been specified to be a VT52. The terminal must be SET TT LC in order to use 
KED or K52. 



SET EMT 

The SET EMT command is used to control tracing of EMT calls during the 

execution of a user program. The form of the command is: 

SET EMT [NO] TRACE 

When SET EMT TRACE is specified, a line of information about the EMT call is 
displayed at the terminal each time an EMT is executed. The .TTYIN, .TTYOUT 
and .PRINT EMTs, however, are not included in EMT traces. EMT tracing is 
disabled with the SET EMT NOTRACE command. Each line of information which is 
displayed during EMT tracing contains: the virtual address of the EMT call, 
the EMT code, function code, channel number (or sub-function code), and the 
first 5 words in the EMT argument block. Only the first two items are defined 
for all EMTs. The other items are defined only if used for the EMT currently 
being traced. As an example of EMT tracing, the LNTT program which displays 
the current line number and terminal type (see Chapter 7) was traced as 
follows: 
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. SET EMT TRACE 
. RUN LNTT 

001004 374 004 000 000000 000000 000610 000000 000000 
001012 375 110 000 057400 001252 001262 001270 001277 

001026 374 005 000 057400 001252 001262 001270 001277 

TSX-Plus line number: 2 

Terminal type: 

001060 375 137 000 001252 001262 001270 001277 001311 

VT-100 

001072 350 016 010 001270 001262 001270 001277 001311 
. SET EMT NOTRACE 

Note that the .PRINT calls are not traced, since .TTYIN, .TTY0UT and .PRINT 
EMTs are never traced. Appendix D contains a list of both RT-11 compatible and 
TSX-Plus specific EMTs. 



SET ERROR 

The SET ERROR command is used to specify the level of error which will abort 

command file execution. The form of this command is: 

SET ERROR option 

where "option" may be FATAL, SEVERE, ERROR, WARNING or NONE. Command files 
being executed under the IND program are not normally aborted if errors occur 
during execution; the SET IND ABORT command can be used to cause IND command 
files to abort according to the same rules as for normal command files. The 
TSX-Plus SET ERROR command functions in the same fashion as the RT-11 SET ERROR 
command. 



SET HIPRCT 

The SET HIPRCT command is used to set the value of the HIPRCT system control 
parameter. See the TSX-Plus System Manager's Guide for more information on the 
effect ot this parameter. The form of this command is: 

SET HIPRCT value 

where "value" sets the non-interactive job I/O counter. Operator privilege is 
necessary to use this command. The HIPRCT parameter may be referenced by the 
SET SIGNAL and SHOW commands. Refer to the TSX-Plus System Manager's Guide for 
more information on job scheduling and performance optimization. 



-48- 



Keyboard Commands 



SET IND 

The SET IND [NO] ABORT command is used to control the execution of command files 
under the control of the IND program when there is an error. Normally, command 
files under the control of IND are not aborted when an error occurs, regardless 
of the current SET ERROR level. However, if the SET IND ABORT command is 
issued, then command files under the control of the IND program will abort 
under the same conditions as would normal command files. The SET IND NOABORT 
command restores the default abort processing under IND control (no abort). 



SET INT IOC 

The SET INTIOC command is used to set the value of the INTIOC system control 
parameter. See the TSX-Plus System Manager's Guide for more information on the 
effect of this parameter. The form of this command is: 

SET INTIOC value 

where "value" is the interactive job I/O counter. Operator privilege is 
necessary to use this command. The INTIOC parameter may be referenced by the 
SET SIGNAL and SHOW commands. Refer to the TSX-Plus System Manager's Guide for 
more information on job scheduling and performance optimization. 



SET 10 

The SET 10 [NOjABORT command is used to select the method of handling I/O abort 
requests. If the SET 10 ABORT command is issued, then an I/O abort request 
will call device handler abort entry points. If the SET 10 NOABORT command is 
issued, then I/O abort requests will proceed through I/O rundown; that is, all 
pending I/O will complete before the job is aborted. The initial setting of 
this parameter is selected during TSX-Plus system generation. Operator 
privilege is required to use this command. The method selected affects all 
lines, not just the line from which the command is issued. 



SET KMON 

The SET KMON command is used to direct the processing of commands from the 

keyboard and from command files. The form of this command is: 

SET KMON option 

where the valid options are: [NO] IND, UCI[=f ilnam] and SYSTEM. The chain of 

events in command processing by TSX-Plus is described at the beginning of this 
chapter. 

The processing of indirect command files may either be controlled by TSX-Plus 
or by the IND utility provided with RT-li. To cause command files to be 
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processed by IND, use the command: SET KMON IND. To return to the normal mode 
of TSX-Plus command file processing: SET KMON NOIND. Note that command files 
which result in errors are not normally aborted, regardless of the SET ERROR 
level, when executed under control of IND. The SET IND [NO] ABORT command can 
used to control error abort of IND command files. Command files may be forced 
to the normal TSX-Plus mode of execution regardless of whether KMON is set IND 
or NOIND by calling them as: 

$@filnam 

Conversely, command files may be forced to execute under the IND utility 
regardless of whether KMON is set IND or NOIND by calling them as: 

IND filnam 

See Chapter 3 for more information on command file processing. 

The other function of the SET KMON command is to control the user command 
interface. It is possible for user written programs to accept and pre-process 
keyboard commands before the TSKMON program. Command control is local to each 
user. That is, each job may select its own command processing method. The 
User Command Interface may be enabled by the command: 

SET KMON UCI[=filnam] 

When UCI is in effect, then each time TSKMON is ready to accept a command it 
passes control to the current UCI program. If the optional "=filnam" has been 
omitted, then TSKMON passes command acquisition control to the program 
SY:UKMON.SAV. If a file has been specified, then TSKMON passes control to that 
program. It is the responsibility of the user-written command interface 
program to prompt for and accept command input lines. Commands may be further 
passed on to TSKMON through the chain-data area by doing a special chain exit. 

Command processing control is returned to TSKMON by the command: 

SET KMON SYSTEM 

See the example program in the section on the User Command Interface earlier in 
this chapter for moxe information. 



SET LANGUAGE 

The SET LANGUAGE command is used to select DBL or DIBOL as the default compiler 
for programs with the extension DBL. This also affects the COMPILE and EXECUTE 
commands. The form of the command is: 

SET LANGUAGE option 

where "option" is DBL or DIBOL. The default setting of this parameter is DBL. 
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SET LP 

The SET LD command is used to control writing to a logical subset disk and to 

verify logical subset disk assignments. The form of the command is: 

SET LDn option 

where "LDn" is in the range of LDO to LD7, and "option" may be CLEAN, WRITE or 
NOWRITE. To prevent writing to a logical subset disk, SET LDn NOWRITE. To 
allow writing to a logical subset disk, SET LDn WRITE. WRITE/NOWRITE control 
is also an option of the MOUNT command. SET LDn CLEAN is used to verify and 
correct logical subset disk assignments. An implicit SET LDn CLEAN is done by 
TSX-Plus whenever the DUP utility program is run (e.g. INIT and SQUEEZE 
operations^ « See the MOUNT command for further information on the use of 
logical subset disks. 



SET LOG 
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enabled, all output directed to the terminal is also written to the log file. 
The only exception to this is high-efficiency terminal output which is not 
logged. To initiate terminal logging issue the following command: 

SET LOG FILE=name 

where "name" is the file specification for the log file. The default extension 
is ".LOG". For example, the following command would copy terminal output to a 
file named "DK:R.UNLST.LOG" : 

SET LOG FILE=RUNLST 

The following command causes terminal output to be copied to the line printer: 

SET LOG FILE=LP: 

Logging of terminal output may be stopped and the log file closed by the 
command: 

SET LOG CLOSE 

The log file is automatically closed when another log file is opened or the job 
logs off. The log file is also automatically closed if the device containing 
the log file is initialized or squeezed; the following warning message appears: 

?KMON-W-Closing log file 
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It may be desirable to suspend and resume terminal output logging during some 
operations without closing and reopening another log file. To temporarily 
suspend terminal logging, issue the command: 

SET LOG NOWRITE 

To resume terminal logging, issue the command: 
SET LOG WRITE 

It may be desirable at some times to reset the terminal log file. To clear the 
contents of the log file without closing and deleting the file, issue the 
command : 

SET LOG CLEAN 

Terminal logging is especially useful with detached jobs. Terminal output to 
detached jobs is normally discarded since the job is not attached to any 
terminal. However, when terminal logging is enabled for a detached job, then 
the terminal output may be directed to a file or to a printer. 



SET LOGOFF 

The SET LOGOFF command is usee to associate a "log-off" command file with a 
job. This command is only valid within start-up command files. The form of 
this command is: 

SET LOGOFF FILE=name 

where "name" is the file specification of a command file to be executed when 
the job logs off. Log-off command files, like start-up command files, cannot 
be aborted by control-C. See the TSX-Plus System Manager's Guide for further 
information about log-off command files. 



SET MAXPRIORITY 

The SET MAXPRIORITY command may be used to reduce the maximum priority allowed 
to a job. When placed in a start-up command file, this command restricts the 
maximum available priority for that job. This permits restriction of priority 
on lines which do not use the LOGON facility. The form of this command is: 

SET MAXPRIORITY value 

where "value" is in the range of to 127. If the current maximum job priority 

is less than 127, then the current maximum priority is the upper limit for the 

valid range of "value". See the TSX-Plus System Manager s Guide for further 
information about restricting job priority. 
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SET NUMDC 

The SET NUMDC command is used to control the number of buffers used for data 

caching. The form of this command is 

SET NUMDC value 

where "value" is the number of buffers to use, The initial value of the NUMDC 
parameter is specified when the system is generated. The SET NUMDC command may 
be used to restrict the number of data cache buffers actually used to a value 
less than the number of buffers specified when the system was generated, but 
may not exceed that value. The SET NUMDC command does not alter the memory 
space allocated for cache buffers, it merely controls the number of buffers 
actually used. Operator command privilege is required to use this command. 

The primary use of the SET NUMDC command is to determine the optimum number of 
data cache buffers to include in a system. To do this, the system can be 
generated with a large number of data cache buffers and the SET NUMDC command 
can be used to determine the minimum number which are actually needed to 
provide effective performance. When using this procedure, all files that are 
being cached should be closed before the SET NUMDC command is issued. See 
Chapter 9 for a discussion of shared-file data caching. 



SET PRIORITY 

The SET PRIORITY command is used to set the execution priority for a time- 
sharing job. The form of the command is: 

SET PRIORITY value 

where "value" may range from to 127. The default priority assigned to a job 
when not otherwise specified or restricted is 50. The maximum priority allowed 
to a job may be restricted through the logon mechanism or the SET MAXPRIORITY 
command. The SHOW PRIORITY command can be used to display the current job 
priority and the maximum authorized priority. The SYSTAT command also displays 
current job priorities. 

Job priorities may also be assigned from within an executing program with an 
EMT. See Chapter 7 for more information on setting job priority from within a 
program. 

When a job is disassociated from the terminal by switching to a different 
virtual line the job is reduced in priority by an amount determined during 
system generation (the PRIVIR parameter). 

The job priority value is used by the scheduler to determine which job has 
precedence and should be run next. The priority value is only used when there 
is more than one job in the same executable state queue. See Appendix H for 
more information about job execution priorities. See the TSX-Plus System 
Manager's Guide for more information on job scheduling. 
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SET PROMPT 

The SET PROMPT command is used to change the keyboard monitor prompt character. 

The default character is a period ("."). The form of the command is: 

SET PROMPT "string" 

where "string" is a quoted string containing from 1 to 8 characters. The 
quoted string will subsequently be used as the keyboard monitor prompt string. 
For example, in order to set the monitor prompt to a dollar sign followed by a 
space (the standard VMS prompt string), use the following command: 

SET PROMPT "$ " 

To restore the standard RT-11 prompt string, issue the command: 

SET PROMPT "." 



SET QUANxx 

The SET QUANxx command is used to set the value of the system time-slice 
control parameters (QUANO, QUAN1A, QUAN1B, QUAN1C, QUAN2, and QUAN3). See the 
TSX-Plus System Manager's Guide for information about the effect of the these 
parameters. The form of this command is: 

SET QUANxx value 

where "value" is the time value specified in 0.1 second units. Operator 
command privilege is required to use this command. The value selected takes 
effect for all jobs on the system, not just the job issuing the command. These 
parameters may be referenced by the SET SIGNAL and SHOW commands. See the 
TSX-Plus System Manager's Guide for more information on job scheduling and 
performance optimization. 



SET SIGNAL 

The SET SIGNAL command is used as an aid to system performance tuning. The 

form of the SET SIGNAL command is: 

SET SIGNAL [NO] parameter 

where "parameter" may be one of the system scheduling parameters: HIPRCT, 
INTIOC, QUANO, QUAN1, QUANlA, QUAN1B, QUAN1C, QUAN2, or QUAN3. Only one 
parameter may be selected by each SET SIGNAL command, although with multiple 
SET SIGNAL commands more than one parameter may be selected for signaling at 
once. Signaling may be disabled for any individual parameter by prefacing the 
parameter with "NO". Signaling may be halted for all parameters with the 
command SET SIGNAL OFF. 
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When signaling has been enabled for a system tuning parameter, the bell will be 
rung at the terminal of the job for which signaling has been selected each time 
the job changes state because it exceeds the value of the selected parameter. 
The SET SIGNAL command functions on a line-by-line basis and only affects the 
line from which the command is issued. 

The signaling feature is intended as an aid to the system manager in deter- 
mining appropriate values of the system tuning parameters for a given job. See 
the TSX-Plus System Manager's Guide for more information on use of the 
signaling feature. 



SET SL 

The SET SL command is used to control the ability to edit keyboard input lines. 
The TSX-Plus SL facility is generally compatible with that provided with the 
RT-11 "SL" editor. It allows editing of the current input line or field and 
recall of the previous input line or field. See the section on the single line 
editor in Chapter 1 for information on the use of the single line editor. The 
form of this SET command is: 

SET SL option 

where the options are described below. 
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ASK This command is ignored. The terminal type is determined from the 
current TSX-Plus terminal type. 

K52 This command enables "KED"-like extensions to the single line editor. 
Note that the numeric keypad is set to application mode. 

KED This command enables "KED"-like extensions to the single line editor. 
Note that the numeric keypad is set to application mode. 

KEX This command enables "KED"-like extensions to the single line editor. 
Note that the numeric keypad is set to application mode. 

[NO] LEARN This command is ignored. The single line editor LEARN mode is not 
implemented. 

[NO] LET This command is ignored. The LET utility may not be used with the 
single line editor. 

OFF This command turns off the single line editor. 

ON This command turns on the single line editor. Note that the job is 
in single-character activation mode. 
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RT11 This command disables the "KED"-like extensions to the single line 
editor. 

SYSGEN This command is ignored. The single line editor is implemented as a 
TSX-Plus system overlay region and does not require the SL pseudo- 
device handler. 

[NO]TTYIN This command either enables (TTYIN) or disables (NOTTYIN) editing of 
keyboard input being accepted via the .TTYIN EMT from within 
programs. 

VT52 This command is equivalent to SET TT VT52. Ensure that your terminal 
responds to VT52 type control sequences before issuing this command. 

VT62 This command is equivalent to SET TT VT52. Ensure that your terminal 
responds to VT52 type control sequences before issuing this command. 

VT100 This command is equivalent to SET TT VT100. Ensure that your 
terminal responds to VT100 type control sequences before issuing this 
command . 

VT101 This command is equivalent to SET TT VT100. Ensure that your 
terminal responds to VT100 type control sequences before issuing this 
command. 

VT102 This command is equivalent to SET TT VT100. Ensure that your 
terminal responds to VT100 type control sequences before issuing this 
command. 

WIDTH=n This command is ignored. The maximum input line width that can be 
used with the single line editor, either as a command line or in a 
program data field, is 80 characters. 



SET TERMINAL 

The SET TERMINAL command is used to set various terminal parameters. It is 

equivalent to the SET TT command. 



SET TT 

The form of this SET command is: 

SET TT [NO] option 

to turn an option off and on. Some options require a numeric parameter, in 
which case they are specified as: 

SET TT option=value 
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Option Meaning 

ADM3A Tells TSX-Plus that the terminal being used is a Lear Siegler ADM3A 
and also has the effect of SET TT SCOPE, NOTAB, NOFORM. 

DECWRITER Equivalent to the LA36 option. 

[NOJDEFER TSX-Plus offers two modes of character echoing — "deferred" and 
"immediate" (NODEFER). If the user only types input to programs 
while they are waiting for input, the two modes function identically. 
However, if the user types input before the program finishes 
processing the previous line of input, the two modes are different. 
In immediate (NODEFER) mode the input characters are echoed immedi- 
ately and may be printed even before the program prints the response 
to the previous line. In deferred echo mode, the characters that are 
typed ahead are accepted and held for the program, but are not echoed 
to the terminal until the program is ready to accept them. Under 
standard RT-11, EDIT, BASIC, and DIBOL programs run in deferred mode. 
Most other programs use immediate echoing. Deferred echoing is the 
preferred mode under TSX-Plus. See Chapter 6 for information about 
how a program can control deferred echo mode. 

DIABLO Has the effect of SET TT NOSCOPE, FORM, NOTAB, PAGE. The QUME type 
is equivalent. When doing plotting or printing with proportional 
spacing, SET TT TAB. 

[NO]ECHO Controls echoing of characters to the terminal. See Chapter 6 for 
information about how a program can control character echoing. 

[NO]FORM Controls conversion of form feed (FF) characters to line feeds. FORM 
should be set with terminals whose hardware can respond to form feed 
characters. NOFORM should be used for terminals whose hardware 
cannot handle form feed characters. When NOFORM is set, form feed 
characters are replaced by eight line feed characters. 

[NOJFORMO The FORMO option causes TSX-Plus to first issue a form-feed when a 
write is done to the terminal with a block number of zero. This is 
convenient when producing multiple program listings to cause each 
listing to begin at the top of a new page. The NOFORMO option 
disables special handling of block zero writes. 



[NO]GAG The GAG option inhibits messages sent from another line from being 
displayed at the terminal. This is only in effect when the job is 
executing a program. Messages are not inhibited while in the 
keyboard monitor. The NOGAG option allows messages to be displayed 
at any time. The GAG option is useful for preventing messages from 
interrupting jobs on hardcopy terminals, such as printers or 
plotters, where a message could spoil the format. This command only 
affects messages sent either with the SEND command or the EMT which 
sends a message to another job. This does not apply to message 
communication channels. 
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HAZELTINE Tells TSX-Plus that the terminal being used is a Hazeltine brand 
terminal and also has the effect of SET TT SCOPE, NOTAB, NOFORM. 

LA36 Tells TSX-Plus that the terminal being used is an LA36 and also has 
the effect of SET TT NOSCOPE, NOTAB, NOFORM. 

LA120 Tells TSX-Plus that the terminal being used is an LA120 and also has 
the effect of SET TT PAGE, TAB, FORM, NOSCOPE. 

[NOJLC Allows lower case characters to be passed to a program. If LC is set 
and bit 14 of the job status word is set to 1, input of lower case 
characters from the terminal will be passed to the running program. 
If the terminal is set NOLC or the Job Status Word bit 14 is clear, 
lower case characters are translated to upper case. See Chapter 6 
for information about how a program can control lower-case character 
conversion. Note that in order to use the keypad editors KED and K52 
the terminal must be SET TT LC. 

[NOJPAGE PAGE allows CTRL-S and CTRL-Q characters to suspend and restart 
terminal output. When the terminal is set NO PAGE, CTRL-S and CTRL-Q 
have no special effect and are passed directly to the running 
program. 

[NOJQUIET Setting the terminal QUIET suppresses the listing of command files as 
they are executed. When the terminal is set NOQUIET, command file 
lines are listed as they are executed. See Chapter 3 for additional 
information on controlling command file listing. 

QUME Equivalent to the DIABLO type. Has the effect of SET TT NOSCOPE, 
FORM, NOTAB, PAGE. When doing plotting or printing with proportional 
spacing, SET TT TAB. 

[NO] SCOPE Tells TSX-Plus whether the terminal is a CRT device. Setting SCOPE 
causes the DELETE key to echo as a backspace-space-backspace 
sequence, erasing the previously typed character. See Chapter 6 for 
information about how a program can specify an alternate "rubout 
filler" character that will be used to overwrite characters being 
erased when DELETE is typed. When the terminal is set NOSCOPE, the 
DELETE key causes preceding characters to be echoed in reverse order 
as they ate removed from the input buffer, and CTRL-U echoes carriage 
return, line feed. CTRL-R can be used to check the current contents 
of the input buffer when doing rubout editing. See Chapter 1 for 
information on other special control characters. 

[NO]SINGL Controls automatic single character activation for programs. If the 
SET TT SINGLE command has been issued, then programs may control 
single character activation on terminal input by toggling bit 12 in 
the Job Status Word. The /SINGLE switch to the R[UN] command and the 
"S" program controlled terminal option allow individual programs to 
control sirigle character activation. The SET TT SINGLE command 
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applies to all programs until the SET TT NOSINGLE command is issued. 
If the SET TT NOSINGLE command is in effect, then programs may still 
individually control single character activation with the 
R[UN] /SINGLE switch or the "S" program controlled terminal option. 
In all cases, the program must still set bit 12 in the Job Status 
Word to achieve single character activation. The SET TT SINGLE 
command differs from the R [UN] /SINGLE switch in that it only affects 
setting of single character activation (JSW bit 12), not terminal 
no-wait input (JSW bit 6). The SET TT NOWAIT command may be used to 
allow no-wait terminal input. 

[NO]TAB Controls conversion of TAB characters to multiple spaces. TAB should 
be selected with terminals whose hardware can respond to TAB 
characters. When set NOTAB, TAB characters being sent to the 
terminal are replaced by an appropriate number of spaces. 



[NO]TAPE TAPE tells TSX-Plus that the terminal line is connected to a paper 
tape, cassette tape, floppy disk or other device that will respond to 
X-ON/X-OFF (CTRL-Q/CTRL-S) control characters to start and stop 
transmission. Setting TAPE mode has three effects: 1) TSX-Plus 
transmits an X-OFF character (CTRL-S) to the terminal when the line 
input buffer fills to the point that there are only 20 free character 
positions remaining; 2) TSX-Plus transmits an X-ON character (CTRL-Q) 
to the terminal when a program begins waiting for more input from the 
line and an X-OFF has previously been sent to the terminal; 3) line- 
e— feed characters are completely ignored unless line— feeu is ueciareu 
to be a user-defined activation character — this is done so that 
each line of input may be terminated by both a carriage-return and a 
line-feed. See Chapter 6 for information about how a ' program can 
turn tape mode on and off. 



VT50 Equivalent to the VT52 option. 

VT52 Tells TSX-Plus that the terminal being used is a VT52 (or VT100 in 
VT52 mode) and also has the effect of SET TT SCOPE, TAB, PAGE, 
N0F0RM. 

VT100 Tells TSX-Plus that the terminal being used is a VT100 (which must be 
operating in VT100 mode — not VT52 compatible mode) and also has the 
effect of SET TT SCOPE, TAB, PAGE, N0F0RM. 

[NOJWAIT Normally, TSX-Plus blocks the execution of a program that does a 
.TTYIN EMT if no activation character has been received even if the 
program sets bit 6 in the Job Status Word which is supposed to mean 
that the program can do non-blocking .TTYIN character tests. This is 
done to prevent programs from "burning up" CPU time by constantly 
looping back to test for terminal input. If the NOWAIT option is 
specified with the SET TT command, TSX-Plus will honor bit 6 in the 
Job Status Word and allow the program to do non-blocking .TTYINs if 
bit 6 is set. The example program "STEALS" in the section on 
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requesting exclusive system control in Chapter 11 demonstrates the 
program controlled terminal option to allow NOWAIT input. 

All of these terminal options can be given initial settings for each line when 
the TSX-Plus system is generated. Each time a user logs onto a line, the 
initial option settings are used. The options may be altered by using the SET 
command, but when the user logs off, the options revert to their initial 
setting specified in TSGEN. When a user initiates a virtual line, the initial 
flag settings for the virtual line are copied from the current flag settings 
for the user. Subsequent flag changes for a virtual line do not affect flag 
settings for the user's other lines. 



SET UCL 

You can specify the order in which the TSX-Plus command interpreter checks for 

user-defined commands by use of the SET UCL command. This command has four 

forms: 

SET UCL FIRST 
SET UCL MIDDLE 
SET UCL LAST 
SET UCL NONE 

If the SET UCL FIRST command is used, user-defined commands will be processed 
before system commands. This allows user-defined commands to replace system 
commands but makes the processing of system commands slower. This is the 
required setting only if it is necessary to replace some system commands. 

If the SET UCL MIDDLE command is used, user-defined commands are processed 
after system commands but before checking for command files and SAV files with 
names that match the command keyword. Using this setting, it is not possible 
to replace a system command with a user command, but both system commands and 
user-defined commands are processed relatively quickly. This is the recom- 
mended setting unless it is desirable to replace system commands. 

If the SET UCL LAST command is used, a command will not be checked to see if it 
is a user-defined command until after it is checked to see if it is a system 
command, the name of a command file on DK, the name of a command file on SY, or 
the name oi a SAV file on SY. Using this setting, it is not possible to 
replace a system command with a user command and user commands cannot have the 
same name as command files or SAV files. System commands are processed quickly 
(the same speed as SET UCL MIDDLE), but the processing of user-defined commands 
is slow. This is the appropriate setting only if user-defined commands are 
desired, but command files already exist whose names would conflict with 
user-defined commands. Existing command files which are short and merely 
execute system commands should be replaced by user-defined commands. 

If the SET UCL NONE command is used, user defined commands are never inter- 
preted. In this mode, attempts to invoke user-defined commands will result in 
the error: 
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?KMON-F -Unrecognizable command 

The following list illustrates where the FIRST/MIDDLE /LAST setting causes the 
command interpreter to check for and process user-defined commands: 

FIRST — > 

See if command is a system command 
MIDDLE — > 

Look for command file on DK: with command name 

Look for command file on SY; with command name 

Look for SAV file on SY: with command name 
LAST — > 

See the beginning of this chapter for further information on the command 
interpretation process. 



SET VM 

The SET VM command is used to control the amount of memory available to the VM 
pseudo-device. The SET VM command is normally not necessary as VM will 
automatically calculate the correct base address to use, starting just above 
the last address used by TSX-Plus, and using all physical memory installed 
above that address. The only form of this command is: 

SET VM BASE=nnnnnn 

where "nnnnnn" represents the octal value of bits 6 through 22 of the base 
memory address which VM is allowed to use. For example, in a system with 1.5 
megabyte of memory, to reserve the top 256 Kb of memory for use by VM the value 
of "nnnnnn" should be 50000. This corresponds to a base address for VM of 
5000000. If this command is issued, then VM will use the higher of the address 
specified by "nnnnnn" or the top of TSX-Plus. That is, it is not permitted to 
set the base of VM to include the system overlay regions. 



SET WILDCARDS 

The SET WILDCARDS command is used to control substitution of missing parts of 

file names. The form of the command is: 

SET WILDCARDS option 

where "option" is either IMPLICIT or EXPLICIT. If IMPLICIT is chosen, then 
file specifications which are incomplete will be treated as though the "*" 
character had been typed for the missing part of the specification. The only 
parts of file specifications affected by this substitution are the file name 
and the extension. The device cannot be specified as a wildcard. Most 
keyboard commands which accept file names also accept wildcards. The following 
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table demonstrates the interpretation of various 
wildcards have been set IMPLICIT or EXPLICIT. 



file specifications when 



Command 


IMPLICIT 


EXPLICIT 


cmd TEST. FOR 


cmd TEST. FOR 


cmd TEST. FOR 


cmd TEST.* 


cmd TEST.* 


cmd TEST.* 


cmd TEST 


cmd TEST.* 


cmd TEST 


cmd TEST. 


cmd TEST. 


cmd TEST. 


cmd *.FOR 


cmd *.FOR 


cmd *.FOR 


cmd .FOR 


cmd *.FOR 


cmd .FOR 


cmd *.* 


cmd *.* 


cmd *.* 


cmd * 


cmd * . * 


cmd * 


cmd .* 


cmd *.* 


cmd .* 


cmd 


cmd *.* 


cmd 



where "cmd" is one of the keyboard commands which accepts wildcards in file 
specifications, such as: COPY, DIRECTORY, PRINT, PROTECT, etc. 

The system-wide default setting for wildcard interpretation may be selected in 
TSGEN; see the TSX-Plus System Manager's Guide. 



The SHOW Command 

The SHOW command is used to display information about the state of the system. 

Each form of the SHOW command is described below. 



SHOW ALL 

The SHOW ALL command is equivalent to specifying all of: SHOW DEVICES, SHOW 
ASSIGNS, SHOW JOBS, SHOW TERMINALS, SHOW MEMORY, SHOW SUBSETS, SHOW MOUNTS, 
SHOW RUN-TIMES. 



SHOW ASSIGNS 

The SHOW ASSIGNS command displays information 

assignments that are currently in effect. 

Example : 

. SHOW ASSIGNS 
Assignments: 
SY — > DLO: 
CBL — > RKO: 
TMP — > DL3: 
DK — > LDO: 



about all logical device 
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SHOW CACHE 

The SHOW CACHE command reports the total number of blocks available in the 

generalized data cache buffer. 

Example : 



.SHOW CACHE 



Number of blocks in data cache = 1000 



SHOW COMMANDS 

The SHOW COMMANDS command is used to display the currently available user- 
defined command definitions. See the beginning of this chapter for more 
information on declaring and using user-defined commands. Note that escape 
characters embedded in commands are represented by a dollar sign ("$"). 



iJAaiupxc • 




.SHOW COMMANDS 


C100 


== DISPLAY $[H$[J 


DEF 


:== ASS ~ DK 


EXAM 


== R KED "/I 


KPAD 


== DISPLAY $- 


LOG : 


== SET LOG FILE=~ 


NEW 


:== R DIR ~/D 


NOKFAD ; 


== DISPLAY $> 


N0L0G 


== SET LOG CLOSE 


Q : 


== SPOOL LP, STAT 


SUB 


:== SH SUB 


TOME 


•== DISMO LD0\ ASS DL2 DK\ SH SUB 


WORK 


== DISMO LD0\ MOU LDO DL2.-W0RK DK\ SH SUB 



SHOW CONFIGURATION 

The SHOW CONFIGURATION causes a display of certain hardware and operating 

system characteristics. 



SHOW CORTIM 



The SHOW CORTIM command displays the current value of the system parameter 
CORTIM. See the TSX-Plus System Manager's Guide for more information on the 
significance of the CORTIM parameter. 
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.SHOW CORTIM 



SHOW DEVICES 

The SHOW DEVICES command displays information about which devices were 
specified as being available when TSX-Plus was generated. For each device the 
following items of information are displayed: 

1. Device name 

2. Device status word (See the RT-11 Programmer's Reference 
Manual, .DSTATUS request, for a description of this value.) 

3. Device handler base address 

4. Device handler size (decimal bytes) 

5. Device CSR (Control and Status Register) address 

6. Device interrupt vector(s) address 

The CSR and vector values are only displayed if the user issuing the SHOW 
DEVICES command has operator privilege. Some of this information is not 
displayed for pseudo-devices such as TT, NL, and LD. 

Example : 



.SHOW 


DEVICES 


Handler 


Handler 






Device 


Status 


base 


size 


CSR 


Vector 


TT 


000004 










DM 


102423 


065302 


1316 


177440 


210 


MT 


016011 


067746 


3844 


172520 


224 


DX 


102022 


077352 


594 


177170 


264 


LP 


020003 


100474 


318 


177514 


200 


NL 


000025 


101172 


58 






LD 


102446 











SHOW HTPRCT 

The SHOW HIPRCT command displays the current value of the system parameter 
HIPRCT. See the TSX-Plus System Manager's Guide for more information on the 
significance of the HIPRCT parameter. 

Example ; 

■ SHOW HIPRCT 
40 
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SHOW INTIOC 

The SHOW INTIOC command displays the current value of the system parameter 
INTIOC a See the TSX-Plus System Manager's Guide for more information on the 
significance of the INTIOC parameter. 

Example ; 

. SHOW INTIOC 
30 



SHOW JOBS 

The SHOW JOBS command displays information about jobs that are currently logged 
onto the system. The information displayed by this command is identical to 
that displayed by the SYSTAT command. 



5HUW MttNUKI 



The SHOW MEMORY command displays information about memory usage including the 
total installed memory on the machine, the size of TSX-Plus and handlers, the 
memory space available to user jobs and the current job memory allocation and 
maximum authorized size. It also lists the size of the swappable job context 
area which is a system table associated with each job. 

i_iivciunJJ- 1; • 



. SHOW MEMORY 

Total installed memory = 1280Kb 

Size of unmapped TSX and handlers = 38Kb 

Size of mapped TSX system regions = 38Kb 

Total size of TSX and mapped data = 80Kb 

Size of sharable run-time systems = 0Kb 

Size of data cache buffer area = 516Kb 

Space available for user jobs = 683Kb 

Swappable context area for each job = 4Kb 

Current job memory limit = 56Kb 

Maximum job memory limit = 64Kb 



SHOW MOUNTS 

The SHOW MOUNTS command displays the names of those devices that have been 
mounted by use of the MOUNT command and whose directories are being cached. 
TSX-Plus maintains a list of which jobs have mounted each device. This list is 
used with the INITIALIZE and SQUEEZE commands to reduce the chance of data 
destruction by altering a device directory while another job has a file open on 
the device. For logical subset disks, the name of the file which contains the 
device is also shown. Note that with nested logical subset disks, the table 
formatting is relaxed. 

-65- 



Keyboard Commands 

Example : 

. SHOW MOUNTS 
Device Associated jobs 

DLO: 1 2 6 8 9 10 11 

DL1: 16 9 

DL2 : SMADA 8 

DL3: 2 11 

DL3:W0RK 11 

DL3: WORK: TEMP 11 

DL3: MANUAL 2 



SHOW NUMDC 



The SHOW NUMDC command displays the current value of the system parameter 
NUMDC. See the TSX-Plus System Manager's Guide for more information on the 
significance of the NUMDC parameter. 

Example : 

. SHOW NUMDC 




SHOW PRIORITY 

The SHOW PRIORITY command displays the current and maximum priority values for 
a job. In addition, the range of priority values which are used for high and 
low fixed priority jobs is shown. See Appendix H for further information about 
job execution priorities. 

Example: 

. SHOW PRIORITY 

Current priority = 50; maximum authorized priority =127 

Low priority range = to 19 

High priority range = 80 to 127 



SHOW QUANxx 

The SHOW QUANxx command is used to display the current value of various system 
tuning parameters. The parameters which may be shown are: QUANO, QUAN1, 
QUAN1A, QUAN1B, QUAN1C, QUAN2, and QUAN3 . Related tuning parameters which may 
also be shown are: CACHE, CORTIM, HIPRCT, INTIOC, and NUMDC. See the TSX-Plus 
System Manager's Guide for more information on the significance of the various 
system tuning parameters. 
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Example ; 

.SHOW QUAN3 
20 



SHOW QUEUE 

The SHOW QUEUE command displays information about print files in the spool 
queue. The following information is displayed for each print file in the 
queue: name of the device the file is queued for; an asterisk if the file is 
currently being printed; the name of the file if a file name was specified with 
the .ENTER — otherwise the name of the program that created the file; the name 
of the form on which the file is to be printed; the number of blocks in the 
file remaining to be printed — this will decrease as the file is printed. For 
more information on printer spooling, see Chapter 5. 



Example: 



r»TT/"\TT /"VTTT^TTTI 



Dev Job File Form Blocks 

LP * 1 PLT50 STD 244 

LP 5 EXTERN STD 5 

LP 5 PAYROL F0RM3 35 



SHOW RUN-TIMES 



The SHOW RUN-TIMES command causes the display of the names o<f the shared 
run-time systems that were loaded with the system. 

Example: 

. SHOW RUN-TIMES 

CBRTS 

RTCOM 



SHOW SUBSETS 

The SHOW SUBSETS command is used to obtain information about logical subset 
disks which have been mounted. Only the logical subset disks which have been 
mounted by the user are shown; those mounted by other users are not included. 
The name of the logical subset disk, the file with which it is associated, the 
file size, and an optional asterisk are displayed. If present, the asterisk 
indicates that the file associated with the logical subset disk is missing. In 
order to DISMOUNT a logical subset disk which is associated with a missing 
file, it is necessary to create or copy the missing file to the appropriate 
device. See the MOUNT and DISMOUNT commands and Appendix G for more infor- 
mation on logical subset disks. 
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Example : 

■ SHOW SUBSETS 

LDO — > DL1: MANUAL. DSK[2 601] 

LD2 — > LD0:SUB.DSK[100] * 



SHOW TERMINALS 



The SHOW TERMINALS command gives a display of the parameters of all primary 
time-sharing terminal lines defined to TSX-Plus during system generation along 
with some current characteristics. 

Example : 

.SHOW TERMINALS 



Unit 



Type 



Vector 



CSR 



Terminal Speed Active User 



1 

2 

3 

4* 

5 

6 



Operator DL 060 177560 VT100 

Local DL 310 176510 VT100 

Local DL 320 176520 LA120 

Local DZ-0 300 160040 VT100 

Local DZ-1 300 160040 VT100 



Remo te 



DZ-3 300 160040 VT52 



N/A 

N/A 

N/A 

9600 

9600 

1200 



Yes 

No 

Yes 

Yes 

No 

No 



SYSMGR 

SMADA 
GREG 



The unit number indicates the number assigned to each line (determined by the 
order of declaration during system generation). The line which issued the 
command is marked with an asterisk. The type of line may be: Operator - the 
line which was declared to be the operator's console during TSX-Plus system 
generation; Remote - any line which has been declared to be attached to a modem 
during system generation; or Local - all other lines. The interface hardware 
is indicated in the Vector column as either a DL(V)11 serial interface or a 
DZ(V)11 multiplexor. DZ lines are further identified with the port number to 
which the line is attached. The Vector and CSR addresses are those declared 
during system generation. The Terminal identification is that which has been 
declared to TSX-Plus either during system generation or via a later SET TT 
<type> command. The Speed column indicates the baud rate specified for DZ type 
lines; it is not available for DL type lines. Lines which are currently logged 
on are marked with a "Yes" in the Active column and the owner is identified in 
the User column If possible. 



SHOW USE 

The SHOW USE command causes display of the accumulated connect time and CPU 
usage for the current job since logon. The SHOW USE command is equivalent to 
the USE command. 
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Example : 

. SHOW USE 

Connect=00:50:00 CPU=00:Q0:23 



The SPOOL Command 

The SPOOL Command is used to control the operation of the spooling system. It 
may only be used if device spooling is enabled when the system is generated. 
The form of the SPOOL command is: 

SPOOL device function oarameter 

where "device" is the name of a device that was specified to be spooled when 
the system was generated, "function" denotes what function is to be performed, 
and "parameter" provides additional information for some functions. See 
Chapter 5 for further information on the SPOOL command. 



The SQUEEZE Command 

The TSX-Plus SQUEEZE command has the same form and options as the RT-11 SQUEEZE 

command. However, the system device (booted device when TSX-Plus is started) 

may not be squeezed while running TSX-Plus. If it is necessary to squeeze the 

system device, it must be done from RT-11. The following error message 

appears: 

?KMON-F-This operation not legal with SY (system) device 

A device cannot be squeezed if any other user has MOUNTed the device. Attempts 
to SQUEEZE a device which is mounted by another user will result in the error 
message: 

?KMON-F-Device is mounted by another user 

The SHOW MOUNTS command may be used to determine which other jobs have the 
device mounted. If the device is mounted only by the job which squeezes it, 
then the directory and data caches are cleared after the operation and caching 
is resumed. 

If terminal logging is being done (see the SET LOG command) and a log file is 
open on the device being squeezed, the log file is automatically closed and the 
following warning message appears: 

?KMON-W-Closing log file 

Warning: It is still possible to write to a device without first mounting it. 
If one user has a file open on a device while another user squeezes the device, 
the possibility of severe data corruption exists. If the user with the open 
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file writes to the disk during or after the squeeze operation, the data will be 
directed to locations on the disk according to the previous directory infor- 
mation. When the disk is squeezed, these locations are no longer appropriate 
and write operations will probably corrupt other files. Never squeeze a disk 
to which another user may be writing data. As a defensive measure, always 
MOUNT any device which you plan to use. 



The SYS TAT Command 

The SYSTAT (SYstem STATus) command displays information about the performance 
of the system and information about each logged-on job. The first line 
indicates the amount of time since TSX-Plus was started or the RESET command 
was issued. The second line of the system performance information shows a 
breakdown of the percent of total time spent running user jobs, waiting for 
user I/O, waiting for swapping I/O and waiting for something to do (idle time). 
These percentages should add up to approximately 100% (less rounding errors). 
The third line of system performance information shows the percent of the total 
time that some user I/O and swapping I/O was being performed. The percentages 
on this line are not expected to sum to 100 because they simply indicate how 
much of the time some I/O was taking place without considering whether jobs 
were running while the I/O was going on. The difference between the I/O 
percentages on the second line and the I/O wait percentages on the first line 
is a measure of the amount of overlap of job execution with I/O that took 
place. The RESET keyboard command may be used to reset these statistics so 
that the statistics may be gathered over a desired interval of system execu- 
tion. 

The information displayed for running jobs consists of one line per job. The 
first item is the job number, followed by an asterisk for the line to which you 
are currently attached. The next item indicates the primary line and virtual 
line number for each job. If the job is a primary line, then the line number 
will correspond to the job number and the number in parentheses will be zero - 
indicating relative virtual job number 0. If the job is a virtual job, the 
line number will indicate the primary line from which it was started and the 
virtual job number relative to the primary line in parentheses. Detached jobs 
will be marked by "Det.". The next item is the current priority for each job. 
A two-character state code is printed next, indicating the current state of the 
job. The state codes and their meanings are as follows: 
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State Meaning 



HI 
IN 
10 
L0 
MI 
MS 
RN 
RT 
SF 
SL 
SP 
TI 
TO 
US 



High priority non-interactive run state 

Interactive state 

Waiting for non-terminal I/O to finish 

Fixed-low-priority run state 

Waiting for mapped I/O buffer 

Waiting for a message 

Normal priority non-interactive run state 

Fixed-high-priority run state 

Waiting for access to a shared file 

Doing a timed wait (.TWAIT) or .SPND 

LTo -f t- -i* n p- fnr froo cnnnl hi ^ft f"»T f i 1p pntrv 

Waiting for input from the terminal 
Waiting for the terminal to print output 
Waiting for access to file management module 



The characters "-Swap" are printed following the state code if the job is 

niir >* r\m *- 1 xt pt.to «t\o/1 /Mif /™* -P *Y»£*Tn/*w -vxt —T ArtV -i o ^ i orvl otta/1 Kit +- Vi <a o-f-o-f-^a ^ /-*•! a. -i -P I-T-* *a 

job has locked itself in memory. The number of K-bytes of memory space used by 
the job, shown next, includes ordinary job space, extended memory regions and 
the job context block (currently 4Kb). This is followed by the connect time 
and CPU time used so far by the job, and the name of the program being run on 
the line. Except for detached jobs, which are not associated with any 
particular user or line, the last item indicates the user name. The user name 
may be blank. 



F.v^TTinl <=> ; 



. SYSTAT 

Uptime: 05:34:29 

System use: Run=10%, I/0-wait=8%, Swap-wait=0%, Idle=81% 

I/O Activity: User 1/0=10%, Swapping 1/0=0% 



Job 


Line 


Pri 


State 


Size 


Connect 


CPU time 


Program 


User name 


1 


1(0) 


50 


Tl-Swap 


33Kb 


05:35:00 


00:03:40 


KM0N 


SYSMGR 


2 


2(0) 


40 


TI 


32Kb 


01:53:00 


00:01:36 


KED 


ANDY 


5 


5(0) 


84 


SL-Lock 


16Kb 


01:00:00 


00:03:17 


LAB 3 


V0LPE 


8 


8(0) 


50 


RN 


34Kb 


05:24:00 


00:00:33 


COBOL 


MITCHELL 


10 


Det. 


50 


MS-Swap 


60Kb 


05:35:00 


00:00:00 


RTS0RT 




11* 


2(1) 


50 


IN 


33Kb 


01:53:00 


00:01:00 


KM0N 


ANDY 



Th e TECO Comm and 

The TECO command is used to initiate an editing session with the TECO editor. 

The TSX-Plus TECO command is equivalent to the RT-11 TECO command. 
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The TIME Command 



The TSX-Plus TIME command has the same form and options as the RT-11 TIME 
command. Operator command privilege is required to set the time. 



The TYPE Command 

The TSX-Plus TYPE command has the same form and options as the RT-11 TYPE 

command. 



The UCL Command 

The UCL command is equivalent to the SHOW COMMANDS command. 



The UN PROTECT Command 

The UNPROTECT command is used to clear file protection status. The TSX-Plus 

UNPROTECT command has the same form and options as the RT-11 UNPROTECT command. 



The USE Command 

The USE command displays the accumulated connect time and CPU usage since 

log-on. 

Example: 

. USE 

Connect=02: 25:00 CPU=00:02:19 



The WHO Command 

The WHO command is used to display information about the system status and 

logged-on jobs. The WHO command is equivalent to the SYSTAT command. 



The $ST0P Command 

The $ST0P command is used to halt the execution of TSX-Plus. On some hardware 

configurations, this may also reboot RT-11. The form of the command is: 

$ST0P 

The $ST0P command forces an immediate logoff of all users before stopping 
TSX-Plus. Operator privilege is required to use this command. If other users 
are logged on, the system will request verification before stopping. Any 
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response beginning with "Y" or "y" will halt TSX-Plus; any other response will 
return to the monitor. For example: 

. $STOP 

Other users are logged on. 

Are you sure you want to stop the system?Y 

Connect=01:14:22 CPU=00:11:15 



The $SHUTDOWN Command 

The $ SHUTDOWN command is similar to the $STOP command in that it is used to 
stop TSX-Plus and may return control to RT-11. However, it differs from $STOP 
in the manner in which it stops TSX-Plus. $STOP forces the immediate logoff of 
all users, $SHUTDOWN does not. Rather, it sets a flag which prevents any new 
users from logging on and then waits for all logged on users to log off. When 
the last user logs off, TSX-Plus is stopped and control may return to RT-11. 
The form of this command is: 

$SHUTDOWN 

Operator privilege is required to use this command. 

2.5 RT-11 Commands not supported by TSX-Plus 

The following RT-11 keyboard commands are not supported by TSX-Plus and are 
ignored if issued: CLOSE, GT, INSTALL, LOAD, REMOVE, RESUME, SUSPEND, UNLOAD. 

The following RT-11 keyboard commands are not supported by TSX-Plus and will 
result in the "Unrecognizable command" error message: ABORT, B, D, E, FRUN, 
GET, REENTER, SAVE, SRUN, START. 

The following keyboard commands have different effects under RT-11 and 
TSX-Plus: BOOT, RESET. 

The following switches are not supported by TSX-Plus with the DIBOL, 
COMPILE/DIBOL or EXECUTE/DIBOL commands: /BUFFERING, /LOG, /PAGE, or /TABLES. 

The following SET options are not supported by TSX-Plus: EL, EXIT, or USR. 
The following SET TT options are not supported by TSX-Plus: CONSOL, [NO]CRLF, 
[NO]FB, or WIDTH. 
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Certain series of keyboard commands may be executed together regularly, or may 
be so complex that it is desirable to edit and proofread them before execution. 
These needs are met by the facility known as indirect command files. These are 
files containing a set of keyboard commands to be executed together. Command 
files are invoked by providing the file name preceded by an "@" symbol in 
response to the keyboard monitor prompt. Command files may also be invoked 
without the "@" if their names do not conflict with system commands. See the 
description of keyboard command interpretation in Chapter 2 for more infor- 
mation on how command files may be initiated. 

TSX-Plus allows the specification of parameter strings to be inserted in a 
command file. The parameters are stored by TSX-Plus and inserted in the text 
of the command file at selected points as the command file is processed. 
TSX=Plus also allows program data as well as system commands to be placed in a 
command file. Under TSX-Plus it is possible to set up a command file so that 
any request for data from device "TT" comes from the command file. This allows 
EDIT and TECO (but not KED) commands to be placed in a command file. 

Command files may be executed either using normal TSX-Plus interpretation or 
under the control of the IND utility. Either type of control may be specified 
either implicitly or explicitly. The keyboard command SET KMON [NO] IND selects 
the desired implicit control of command files. If KMON is set IND, then 
command files will normally execute under the control of the IND program. If 
KMON is set NOIND, then command files will normally execute under TSX-Plus 
control. Regardless of the setting of KMON, a file may be executed under 
control of IND by typing: 

IND file 

Regardless of the setting of KMON, a file may be started as a normal command 
file (not under the control of IND) by typing: 

$@ file 

Examples: 

1. Execute the command file DK: DAILY.COM under control of the IND 
utility regardless of the setting of KMON: 

. IND DAILY 

2. Execute the command file DLl: WEEKLY. COM under normal TSX-Plus control 
regardless of the setting of KMON: 

.$@DL1: WEEKLY 
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3.1 Invoking command files 

A command file is invoked by typing: 

^filename [paraml [param2 ... [param6] ] ] ] ] ] 

where "filename" is the name of the command file and "paraml", "param2", etc. 
are optional parameter string arguments to the command file. The default 
extension for a command file is "COM". 

When the name of a command file does not conflict with a system command, the 
command file may be invoked by typing: 

filename [paraml, .. .par am6] 

That is, the "@" may be left out. With or without the "@" sign, if no device 
is specified device "DK" is first searched for the command file. Then, only 
without the "@" sign, if the named file is not found, then TSX-Plus attempts to 
locate the command file on device "SY". See Chapter 2 for a description of the 
steps used by TSX-Plus to interpret keyboard commands. Listing control for 
command files differs whether the "@" sign is used or not. If the "@" is used, 
then listing is controlled by the current value of the SET TT [NOJQUIET option. 
If no "@" is used, then listing is disabled — as if a SET TT QUIET had been 
issued. In either case, the command file itself can control its own listing 
status with a SET TT [NOJQUIET command or with the control characters described 
later in this chapter. 

3.2 Parameter strings 

Parameter strings are normally delimited by spaces. Thus in the command: 
@TSTRUN ABC 123.45 2/3 

the string "ABC" is parameter 1, "123.45" is parameter 2 and "2/3" is parameter 
3. In some cases it may be desirable to include spaces as part of a parameter 
string. If this is to be done, the first parameter must begin with the 
character "\" (left leaning slash), and the left-slash must be used as the 
parameter delimiter rather than spaces. For example, in the command line: 

@TSTRUN \A STRING\OF PEARLS 

parameter 1 is "A STRING" and parameter 2 is "OF PEARLS". 

Up to six parameter strings may be specified when the command file is started. 
The total number of characters in the combined parameter strings may not exceed 
60. 
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Parameter strings are inserted into the command file during execution at 
locations specified by an up-arrow ("~"). The parameter to be inserted is 
designated by a digit (1 to 6) immediately following the "~". During execution 
of the command file, the "up-arrow-digit" sequence is replaced by the parameter 
string passed to the command file in the position specified by the digit. If a 
parameter string is called for that was not specified when the command file was 
invoked, the up-arrow-digit will be ignored and no characters will be inserted 
in their place. For example, consider the following command file named 
TEST.COM: 



When this command file is invoked with the following command: 

@TEST FORTRAN PROG 

the command file is executed as if it contained the commands: 

R FORTRAN 
=PR0G 

Command files may be nested. That is, one command file may call another 
command file. When such a call occurs, the parameter strings for the outer 
level (calling) command file are stored on a stack in TSX-Plus and then the 
parameter strings for the called command file are set un- When the called 
command file finishes, the parameters for the calling command file are 
restored. The maximum depth of nesting is governed by the size of the 
parameter string stack and the length of the actual parameter strings. A 
nesting depth of 3 can be reached even with very long parameter strings. If no 
parameters are specified, the nesting depth may go to about 7 levels. 

The command file listing status (SET TT [NO] QUIET) is also stacked as command 
files are nested. This means that an inner nested command file may have its 
listing turned on or off. When its execution is completed and control returns 
to the next outer level command file, the listing control is reset to the state 
in effect when the inner command file was called. This is not done for the 
outer-most command file, however, so the SET TT [N0]QUIET state in effect on 
completion of the outer level command file remains in effect when control is 
returned to the keyboard monitor. 

3.3 Comments in command files 

Comments may be included in command files following an exclamation point ("!"). 
Anything on a line in a command file following an exclamation point will be 
treated as comment. For example, in a command file containing the lines: 
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DISPLAY Watch out! Files may be destroyed. 

PAUSE Hit RETURN to proceed .'Requires operator response 

the resulting output would be: 

Watch out 

PAUSE Hit RETURN to proceed 

» 

When an exclamation mark ("!") is used in a command file line to be input as 
data to a program, then the exclamation mark and all text following it on the 
input line are not passed to the program. 

3.4 Command file control characters 

Several combinations of characters take on special meaning when they are found 
within a command file. The up-arrow character ("~") followed by a letter is 
replaced by the control character corresponding to the letter specified. Thus 
"~C" becomes control-C. The escape character may be represented by up-arrow, 
dollar sign ("~$"). The up-arrow character itself may be represented in the 
command file by preceding it with another up-arrow ("~~"). 

Several character combinations act as special commands to influence the 
execution of the command file. These commands take effect at the point of 
their occurrence in the command file. The characters in these special 
sequences are not passed to programs. 

Command 

Sequence Function 



~( Stop listing command file. This has the same effect as SET TT 
QUIET, except that it only applies to the current command file. 

*) Start listing command file. This has the same effect as SET TT 
NOQUIET except that it only applies to the current command file. 

~! Suppress all terminal output. Both the command file listing and 
any program terminal output are suppressed. The "*(" and "~)" 
command sequences restart program generated output. 

~> Accept all terminal input from the command file. Command file 
data is normally only passed to programs which request lines of 
input (using the EMT calls: .GTLIN, .CSISPC and .CSIGEN). 
RT-11 handles command file data in this manner. Programs called 
by a command file which request terminal input with the EMT 
calls .TTYIN or .READ normally still expect to get this from the 
terminal and cannot use command file data as input to these 
requests. The "~> M command sequence causes all subsequent 
requests for terminal input to come from the command file 
regardless of which EMT is used. This allows data for appli- 
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cation programs to be placed in a command file. It also allows 
commands for TECO and EDIT to be placed in a command file. This 
command only affects input requests that occur after TSX-Plus 
reads the "~>" sequence. See also the description in Chapter 6 
of the "N" and "0" program controlled terminal options that 
affect command file input. 

~< Return to standard data mode. Subsequent command file data will 
only be passed to programs which do .GTLIN, .CSISPC or .CSIGEN 
EMTs (standard RT-11 mode). 

~Z Control-Z is translated to control-C in command files. 

3.5 PAUSE Command 

The PAUSE command is provided to suspend the execution of a command file while 
the operator performs some manual operation. The form of the PAUSE command is: 

PAUSE comments 

where "comments" may be any string of characters. When a PAUSE command is 
executed, the PAUSE command is displayed at the terminal followed by "»". 
Execution of the command file is then suspended until carriage return is typed. 

3.6 DISPLAY Command 

The DISPLAY command causes a line of text to be displayed at the terminal. The 
form of the DISPLAY command is; 

DISPLAY comments 

where "comments" may be any line of text to be printed at the terminal. This 
is useful to mark progress through command files running in "quiet" mode (not 
being listed). 
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4^_ VIRTUAL TIME-SHARING LINES AND DETACHED JOBS 

4.1 Virtual Lines 

TSX-Plus provides a facility known as "virtual lines" which allows one 
time-sharing user to simultaneously control several running programs from a 
single terminal. When initially logging on to TSX-Plus, the user is connected 
to the "primary" time-sharing line, also called virtual line number (zero). 
At any time, the user may switch to a different virtual line. This has the 
effect of logically disconnecting the time-sharing terminal from the current 
virtual line and connecting it to a different logical line. Note that when 
normal priority jobs are disconnected from a terminal by switching to a virtual 
line, the priority of the disconnected job is reduced by an amount selected 
during system generation. Jobs in either the fixed-high- or fixed-low-priority 
ranges do not suffer this priority reduction. 

If a program is running when the switcu is maue, its execution is not a^iecteu 
(but it is given a lower CPU priority). If a program is running on a line that 
is not not currently connected to the terminal and that program writes output 
to the terminal, the output is not displayed at the terminal, but is instead 
stored in a terminal output buffer. When this buffer is filled, the program is 
suspended (and the job may be swapped out of memory) until the terminal is 
reconnected to the virtual line. On a disconnected virtual line, if the output 
buffer becomes full or if a program requests terminal input, the bell is rung 
on the line which is currently connected to the terminal to indicate that a 
virtual line needs service. 

To switch to a virtual line, type control-W (hold down CTRL key and press W) 
followed by a single digit (do not hold down CTRL while typing the digit). The 

rH&if iHpnfi fipR whirh virtual Ii'tip 1-Vip nspr wi rVip.c tn arrpflQ. Of-h^r nsprs maxr 

be using virtual lines of the same relative number without conflict. The 
CTRL— W digit sequence may be entered at any time - even in the middle of a line 
of input. The command takes effect immediately and leaves the old line in an 
undisturbed state. (On later return to the primary line, CTRL-R may be used to 
display a partial input line which had already been typed.) TSX-Plus responds 
to CTRL-W, digit by printing "n>" on the terminal, where "n" is the relative 
number of the virtual line that has ^ust been accessed* Note that the relative 
virtual line number does not correspond to the job number. The SYSTAT command 
may be used to determine the job number and, for virtual lines, to determine 
the primary line from which virtual lines were started and their virtual line 
numbers relative to the primary line. The primary line can always be accessed 
with the sequence "<CTRL-W>0" , since the primary line is virtual line number 0. 
(Note that the system manager may select a signal character other than 
control-W to indicate a request to switch to a virtual line.) 

If a start-up command file was specified for the primary line, it will also be 
executed when the virtual line is initiated. If the LOGON program is run as 
part of the start-up command file for a virtual line, it will automatically log 
the user on to the account specified when logging onto the primary line. 
Therefore , logical assignments made in a start-up or LOGON command file are 
defined for the virtual line. However, other logical assignments are not 
inherited by the virtual line. Any user defined commands in effect for the 
primary line are inherited by a virtual line when it is started. 
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The user logs off a virtual line by typing the "OFF" command. When a user logs 
off a virtual line other than the primary line, that virtual line is returned 
to the pool of free lines and the user is automatically reconnected to the 
primary line. When a user logs off the primary line, not only is the primary 
line released, but any virtual lines the user may have been using are also 
released, and the user is disconnected from the system. Note that it is 
possible (and frequently desirable) to switch back and forth between the 
primary line and one or more virtual lines without logging off any. 

The total number of virtual lines and the maximum number of virtual lines which 
any user may utilize at a given time are determined by the system manager. An 
attempt to log on to a virtual line number higher than the maximum allowed for 
each user, is ignored. The CTRL-W, digit sequence is also ignored if the user 
is already connected to the maximum number of virtual lines allowed or if no 
free virtual lines are available. 

Virtual lines are quite useful in situations where the user wishes to execute a 
long "number crunching" job without tying up a line. Simply start the long job 
and switch to another virtual line. The CPU priority of the disconnected job 
is reduced so that it interferes little with normal time-sharing operations, 
but rather "soaks up" idle CPU time. Such low priority jobs run only when no 
high priority jobs are running. 

The keypad editors KED and K52 use the CTRL-W key to repaint the screen. Under 
TSX-Plus, use two successive CTRL-W's to repaint the screen with these editors. 
A conflict arises when switching to a virtual line while in a keypad editor and 
performing another editing job on the second virtual line. When exiting the 
second edit job, the editor automatically restores the terminal from alternate 
(application) keypad mode to numeric keypad mode. Then, on returning to the 
first editing job, it is not possible to use keypad commands since the keys no 
longer generate the correct sequences. To avoid this, either do not use keypad 
editors on more than one virtual line simultaneously, or restore the terminal 
to alternate keypad mode before returning to the original editing job. To set 
either VT-100 or VT-52 type terminals to the alternate keypad mode, send the 
two character sequence "<ESC>=" to the terminal. 

4.2 Detached jobs 

The TSX-Plus Detached job facility is similar to the virtual line facility: 
they both allow a timesharing user to execute several jobs simultaneously. The 
major difference between detached jobs and virtual lines is that you may switch 
back and forth among virtual lines, but once a detached job is started it is 
dissociated from any terminal. Detached jobs operate more like a "batch" 
facility. ALL terminal input for a detached job must come from a command file. 
Any terminal output generated by a detached job is discarded. However, 
terminal logging may be enabled for detached jobs to accept their terminal 
output; see the SET LOG command. 
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The differences between virtual lines and detached jobs are summarized below. 

1. With virtual lines, terminal communication may be switched between 
several running jobs. A detached job must receive all its terminal 
input from a command file and any terminal output it generates is 
discarded (unless terminal logging directs the output to a log file). 
If a detached job requests -terminal input and is unable to obtain it 
from a command file, the job is terminated. 

2. Virtual lines are "owned" by a physical line. When the physical line 
logs off, the virtual lines also log off. Detached jobs are not 
associated with any physical line. Once started, any or all 
time-sharing users may log off without affecting detached jobs. 

3. Detached jobs may be started automatically when TSX-Plus is initi- 
ated. Virtual line jobs must be started by time-sharing users after 
TSX-Plus is running. 

4. When a detached job reaches the end of its command file and asks for 
more terminal input, the job is aborted and the detached job slot is 
freed. Virtual lines wait for more input. 

There are three ways to start detached jobs: 1) during system generation 
specify a command file to be started as a detached job whenever TSX-Plus is 
started; 2) use the keyboard DETACH command; 3) use the TSX-Plus EMT to start a 
detached job from a running program. Detached jobs that are initiated 
automatically when the system is started run with operator privilege. Detached 
jobs initiated by use of the DETACH command or the EMT inherit the privilege of 
the user starting them. 

4.2.1 The DETACH command. 



The DETACH command is used to start a detached job, check its status and abort 
the job. The system manager may restrict the use of the DETACH command. 

4.2.1.1 Starting a detached job: The form of the DETACH command used to start a 
detached job is: 

DETACH file-spec 

where "file-spec" is the name of a command file to be executed as a detached 
job. The default device is "SY:" and the default extension is "COM". The 
default disk "DK" is not used because no_ logical assignments are passed to the 
detached job , either in the detach command itself or in the command file 
started with it. When a request is made to start a detached job, TSX-Plus 
searches for a free detached job slot. The total number of such job slots is 
established when TSX-Plus is generated. If a free slot is found, the job is 
started and a message is printed saying which job slot was used. This number 
may be used later to reference the detached job. The SYSTAT command also 
indicates detached job line numbers and flags detached jobs with "Det.". A 
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detached job started by use of the DETACH command inherits the privileges (but 
not any logical assignments nor any logical subset disks declared after logon) 
of the user who is starting the job. If "file-spec" is preceded by the symbol 
"@", then the first line of the command file will be used by the detached job, 
but any remaining commands in the file will be associated with the job 
currently connected to the terminal. 

Neither the DETACH command itself nor the command file started with it inherit 
any logical device assignments. 

Examples: 

1. Start a command file "SY: PURGE. COM" as a detached job. 

. DETACH PURGE 
Job started on line #9 

2. Start a command file named "RK1: STATS. NEW" . 

. DETACH RK1: STATS .NEW 
Job started on line #8 

3. Start the first line of "SY: MAKIT.COM" as a detached job, 
and use subsequent lines as an ordinary command file. 

. DETACH @MAKIT 
Job started on line #9 

The system manager determines the number of slots available for detached jobs 
and who may use detached jobs. The job numbers assigned to detached jobs start 
after the slots reserved for primary time-sharing lines. Virtual lines are 
assigned line numbers above any slots reserved for detached jobs. 

4.2.1.2 Checking the status of a detached job: The form of the DETACH command 
used to check the status of a detached job is: 

DETACH/CHECK line-number 

where "line-number" is the job slot number listed when the job was started. 
TSX-Plus displays the status (active or free) of the detached job. 

Examples: 

1. Check the status of the job on line #4. 

. DETACH/CHECK 4 
Line is active 
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2. Check the status of the job on line #5. 

. DETACH/ CHECK .5 
Line is free 

4.2.1.3 Aborting a. detached job: The form of the DETACH command used to abort 
a running detached job is: 

DETACH/KILL line-number 

where "line-number" is the job slot number listed when the job was started. 
For example, to kill the detached job on line #4: 

. DETACH/KILL _4 
Job aborted 

4.2.2 Detached job control EMTs. 

TSX-Plus provides a set of EMTs that can be used to control the operation of 
detached jobs. Using these EMTs it is possible to start a detached job, kill a 
detached job and check the status of a detached job. 

4.2.2.1 Starting A Detached Job: This EMT can be used to start the execution 
of a detached job. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,132 

.WORD name-address 

where "name-address" is the address of an area containing the name of the 
command file to be started as a detached "iob* The command file name must be 
stored in ASCIZ form and may contain an extension. If a free detached job line 
is available, the specified command file is initiated as a detached job and the 
number of the detached job line is returned in RO. A detached job started by 
use of this EMT inherits the privileges of the job that is executing the EMT. 
If there are no free detached job lines, the carry bit will be set on return. 



Example : 



.TITLE STRTDJ 
.ENABL LC 



; Start a job on a TSX-Plus detached line 

CR = 15 
LF = 12 
ERRBYT =52 
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.MCALL .ENTER, .WRITW, .CLOSE, .PRINT, .EXIT 



1$: 



.ENTER #AREA,R1,#FILR50,#1 



START: CLR Rl ; Channel number 

;No .FETCH is necessary under TSX-Plus, handlers are always resident. 

;Open a one block file 
;on first free channel. 
; Branch on successful .ENTER 
;Why didn't .ENTER work? 
;Error = 1 :not enough room for file 
;Try next higher channel 
;Last channel? .CDFN not supported by 
;TSX-Plus, so legal channels are 0-15. 
;0K, retry on next channel 
;Ran out of channels 



2$: 



BCC 


2$ 


TSTB 


@#ERRBYT 


BNE 


N0R00M 


INC 


Rl 


CMP 


Rl,#17 


BLE 


1$ 


.PRINT 


#NCA 


BR 


DONE 


.WRITW 


#AREA,R1 


BCS 


WRTERR 


.CLOSE 


Rl 


MOV 


#STRTDJ V 


EMT 


375 


BCS 


DTCHER 


BR 


DONE 



#AREA, Rl , //COMNDS , #«CMDEND-C0MNDS+l>/2>, #0 
;Bad write? 
;Close the file 
; Point to EMT arguments to 
;Start the detached job 
;Bad start of detached job? 



N0R00M: .PRINT #NER 



BR 



DONE 



WRTERR: .PRINT #BADWRT 

.CLOSE Rl 

BR DONE 

DTCHER: .PRINT //BADDET 

DONE: .EXIT 



;Not enough room error 
;. WRITW error 

;STRTDJ error 



AREA: 
STRTDJ: 



FILR50: 

FILNAM: 

COMNDS : 

CMDEND: 

NER: 

NCA: 

BADWRT: 

BADDET: 



.BLKW 5 

.BYTE 0,132 

.WORD FILNAM 

.NLIST BEX 

.RAD50 /SY CKSTATCOM/ 

, ASCIZ /SY: CKSTAT.COM/ 



;EMT Argument area 

;EMT arguments to start a detached job 

; Pointer to name of command file 

;RAD50 name of command file to be detached 
;ASCII name of command file to be detached 



.ASCIZ /R CKSTAT/<15><12> ; Start a monitoring program 

.ASCIZ /?STRTDJ-F-Not enough room for command file./<7> 

.ASCIZ /?STRTDJ-F-No channels available for command file,/<7> 

.ASCIZ /?STRTDJ-F-Error writing command file./<7> 

.ASCIZ /?STRTDJ-F-Error starting detached job./<7> 



.END 



START 
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4.2.2.2 Aborting a. detached job: 
The form of the EMT is: 



This EMT may be used to abort a detached job, 



EMT 



375 



with RO pointing to the following argument block: 



.BYTE 
.WORD 



2,132 
job-number 



where "job-number" is the job number of the detached job to be killed. If the 
job number is not valid for detached jobs, the carry flag will be set on return 
and the EMT error byte will be set to 1. 



Example 



.TITLE CKABDJ 
.ENABL LC 



; Check status of a detached job and abort it if running 

.MCALL .EXIT, .PRINT 



START: MOV 
EMT 



#STATDJ,R0 
375 
BCC 1* 

.PRINT //NOTON 
.EXIT 

MOV #ABRTDJ,R0 

EMT 375 

BCS ABERR 

. PRINT #KILLED 
.EXIT 



ABERR: .PRINT #ABERMS 
.EXIT 



1$: 



; Point to EMT arg block to 

; Check status of a detached job 

• T f q f- 1 1 1 mn W 1 1 if 
> -■-■*- "<--- — — ~", ^j-^-w j.». 

;Else, say it isn't active 



; Point to EMT arg block to 

;Abort detached job 

; Since we checked, should never err 

: Sav we killed it 



STATDJ: 


.BYTE 




.WORD 


ABRTDJ: 


.BYTE 




.WORD 




.NLIST 


ABERMS : 


.ASCIZ 


NOTON: 


.ASCIZ 


KILLED: 


, ASCIZ 



1,132 

9. 

2,132 

9. 

BEX 

/?CKABDJ-F-Invalid detached job number /<7> 

/?CKABDJ-I-No detached job on line #9/<7> 

/Detached lob on line #9 killed./ 



;EMT arg value to check detached job status 
;Line number of detached job to be checked 
;EMT arg value to abort a detached job 
;Line number of detached job to be killed 



.END 



START 
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4.2.2.3 Checking the status of a. detached job: This EMT may be used to check 
the status of a detached job. The form of the EMT is: 

EMT 375 
with RO pointing to the following argument block: 

.BYTE 1,132 
.WORD job-number 

where "job-number" is the number of the detached job to be checked. If the 

detached job is still active the EMT returns with the carry-flag cleared. If 

the detached job has terminated and the detached job line is free, the EMT 
returns with the carry-flag set. 

Example: 

See the example program CKABDJ in the previous section. 
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5.1 The concept of device spooling 

Device spooling is a technique that provides more efficient use of slow 
peripheral devices. Data sent to spooled devices is automatically redirected 
to a high speed disk file for temporary storage and sent to the slow device 
when it is ready to accept it. This allows a program generating data for the 
spooled device to continue processing without being slowed down by the 
peripheral. TSX-Plus optionally provides automatic spooling to output devices 
such as printers, card punches and plotters. Several devices may be spooled on 
a system. 

When a program directs output to a spooled device, the output is diverted by 
TSX-Plus to a spool disk data file. An entry is made in a spool file table 
indicating a spool file is ready for the spooled device. When the spooled 
device becomes free, the spool file is copied by TSX-Plus to the device. All 
of the processing is automatic and the user does not have to be concerned with 
its operation. In fact, a user can run programs without waiting for their 
output to be printed. Devices to be spooled must be declared when the system 
is generated. 

Spooled device handlers such as LP must be set to the "HANG" mode of operation 
to work properly with the TSX-Plus spooler. This can be done with the SET 
command. For example: 

.SET LP HANG 

Since the SET command actually stores this information permanently in the disk 
copy of the device handler, it need only be issued once. 

5 . 2 Directing output to spooled devices 

Output is directed to a spooled device in exactly the same way it would be 
directed to the device if it were not spooled. For example, if the line 
printer (LP) were spooled, the following commands would send a FORTRAN listing 
to the printer: 

.R FORTRA 
*TEST,LP:=TEST 

The name of a spooled device may be used in a MACRO .ENTER command just as a 
non-spooled device would. 

Any number of users may simultaneously write to a spooled device without 
conflict. TSX-Plus separates the output from each user and prints it in an 
orderly fashion. A user may direct output through several I/O channels to the 
same or different spooled devices. 

5.3 Operation of the spooler 

The spooling system consists of a memory resident spool file control table 
which contains information concerning the user's spool file and a single system 
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managed spool data disk file which contains the user's intercepted output. 
Every time a user opens an output channel to a spooled device, a new entry is 
created in the spool file control table. Output records directed through 
separate channels to the same device have separate entries in the spool file 
control table. Placement in this table is governed by the processing of the 
user's open request for the spooled device. 

The total number of spooled files that may be in existence is specified when 
TSX-Plus is generated. A spooled file is created when an I/O channel is opened 
to a spooled device; the file remains in existence until all of the output is 
processed by the spooled device. If a program opens a channel to a spooled 
device and the spool file control table already contains the maximum number of 
spooled files, the program is suspended until a slot becomes available in the 
spool file control table. 

All output directed to spooled devices is stored in a common disk data file. 
The total file space that is available for spooled data is specified when the 
TSX-Plus system is generated. Space within this disk file is dynamically 
allocated as needed on a block by block basis. Each block contains 508 bytes 
of user's output data. Therefore, write requests smaller than 508 bytes will 
be combined into one spool data block. A write request larger than 508 bytes 
will be split into more than one spool data blocks. If the spool data file is 
totally filled, programs writing to the spooled device will be suspended until 
space becomes available. 

Actual output to the spooled devices is processed on a sequential first- 
in/first-out basis. Since output is actually coming from the disk file, each 
I/O request to the device handler is the size of the spool data block (508 
bytes). While spooled files are being printed, TSX-Plus maintains a list of 
the blocks most recently printed. The length of this list is specified by the 
number of backup blocks declared during system generation. When the list 
becomes full, the oldest block is deallocated and the new block is added. When 
the entire spooled file has been successfully written, the entire list is 
deallocated. 

5.4 The SPOOL Command 

The SPOOL command is used to control the operation of the spooling system. The 
form of the SPOOL command is: 

SPOOL device, function, parameter 

where "device" is the name of a spooled device, "function" indicates the 
operation to be performed, and "parameter" is an optional item of information 
used with some functions. Each of the available functions is described below. 

The FORM and LOCK Functions 

The FORM and LOCK functions are used to specify the name of the currently 
mounted form. The form name is specified in the "parameter" field of the 
command. The FORM function allows TSX-Plus to request a form mount when a 
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different form is needed. The LOCK function specifies that the form is to be 
locked on the printer and disables form mount request messages. 

Examples: 

. SPOOL LP, FORM, BILLS 
. SPOOL LP, LOCK, BILLS 
. SPOOL LP,FORM,STD 

Note the difference between the FORM keyboard command and the SPOOL command 
with the FORM or LOCK functions. The FORM command is used by the TSX-Plus user 
to specify the default form name to be used for subsequent spool files. The 
SPOOL FORM/LOCK commands are used by the TSX-Plus operator to tell the spooling 
system which form is currently mounted. 

The ALIGN Function 

The ALIGN function is used to print a form alignment file on a spooled device. 
The name of the alignment file is specified in the "parameter" field of the 
command. The default file extension for form alignment files is "ALN". 

Examples: 

. SPOOL LP, ALIGN, BILLS 

. SPOOL LP, ALIGN, RK1: PAYROL.DAT 

.SPOOL LP,ALIGN,DX:RP0RT2 



The DELETE Function 

The DELETE function is used to abort printing of the file currently being 
printed on the indicated spooled device. The spooler waits for the most recent 
I/O request to complete before deallocating all disk data blocks associated 
with the deleted spool file. The DEL function has no effect if no file is 
currently being printed. 

Examples : 

. SPOOL LP, DELETE 
.SPOOL LS, DELETE 



The SKIP Function 

The SKIP function causes the spooler to skip over the next n. blocks in the 
spool file that is currently being printed, where n. is specified in the 
parameter field of the instruction. Each block in the spool data file contains 
508. characters. Printing of the file continues after the indicated number of 
blocks have been skipped. 
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Examples : 

. SPOOL LP, SKIP, 10 
. SPOOL LP, SKIP, 100 

The BACK Function 

The BACK function causes the spooler to skip backward in the spool file a 
number of blocks and then resume printing at that point. The number of blocks 
involved is specified when TSX-Plus is generated. Each block in the spool data 
file contains 508. characters. This function is particularly useful for 
recovering from paper tears or remounts. The spooler will finish printing the 
current block before backing up. 

Examples: 

. SPOOL LP, BACK 
. SPOOL LS,BACK 

The STAT Function 

The STAT function is used to determine the status of a spooled device. 

Information returned includes: the condition of the spooler (active, idle, or 

waiting for a form mount); the name of the currently mounted form; and 

information about files waiting to be printed on the device. The SHOW QUEUE 

command may also be used to display information about files in the spooler 

queue. 

Example: 

. SPOOL LP, STAT 

Spooler idle 

Currently mounted form = STD 

No files in queue 

The SING and MULT Functions 

The SING and MULT functions control how the spooler will handle multiple files 
queued for the same form. In "MULT" mode (the initial setting) no form mount 
request message is generated if a spool file is found that needs the currently 
mounted form. Processing of the file begins automatically. 

In "SING" mode a form mount request is generated for every file even if the 
file needs the currently mounted form. This is useful where equipment setup or 
form alignment is needed for every file. 

Examples : 

. SPOOL LP, SING 
. SPOOL LP, MULT 
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The HOLD and NOHOLD Functions 

A spooled device that is in the HOLD mode will not begin to process a spool 
file until the file is completely created and the I/O channel associated with 
the file is Closed. A spooled device that is in NOHOLD mode will begin to 
process a spool file as the file is being created. In NOHOLD mode, the spooler 
will begin to process a file sooner; however, if the file is being created 
slowly, the spooled device will remain busy (and unavailable to other users) 
for as long as it takes to finish generating the file. If the spool storage 
file is completely filled, the spooler will attempt to free space by beginning 
to process open spool files even if HOLD is in effect. 

The default [NOJHOLD mode is established when the TSX-Plus system is generated. 
A [NOjHOLD command remains in effect until another [NO] HOLD command is issued 
or the system is restarted. 

Examples: 

. SPOOL LP, NOHOLD 
.SPOOL LP, HOLD 



It is also possible to dynamically request that a file being printed through 
the spooler be either held until the file is closed or begin printing as data 
is made available from the program. This could be used in a situation where 
NOHOLD is the normal condition, but a program which uses the printer generates 
data slowly. If data were passed to the printer as soon as available, then 
printer output from all other ^obs would be delated until the slow "iob closes 
the output. This can be avoided by the having the slow program select hold 
mode for its output. Then, other jobs can proceed to use the printer without 
being delayed by the slow job. The form of the EMT to select hold or nohold 
mode on an individual file basis is: 

EMT 375 

with RO pointing to the following argument block: 



.BYTE 


chan,151 


.WORD 





.WORD 


flag 



where "chan" is the channel number which has been used to open the print file 
and "flag" indicates whether the file is to be printed as it is generated or 
held until the file is closed. If "flag"=0, the output is printed as generated 
(equivalent to NOHOLD); if "flag"=l, then the output is not printed until the 
file is closed. This EMT must be issued after a channel has been opened to the 
printer (through the spooler), but before any data has been written to it. If 
the channel is open to any non-spooled device, then the EMT is ignored. 
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Example : 



.TITLE SPHOLD 
.ENABL LC 



Demonstrate the EMT to hold spooler output until the file is closed 



.MCALL 
ERRBYT = 52 
START: .CSISPC 

BCS 

MOV 
OPNFIL: .LOOKUP 

BCS 

MOV 

MOV 

ADD 

MOV 

MOV 

TST 

.LOOKUP 

BCC 
GIVEUP: .CLOSE 

.EXIT 



.CSISPC, .LOOKUP, .READW, 

#OUTSPC,//DEFEXT,#0 

START 

#INSPC,R1 

#AREA,#0,R1 

START 

#OUTSPC,R2 

#~RLP ,(R2)+ 

#2,R1 

(Rl)+,(R2)+ 

(R1)+,(R2)+ 

(Rl)+ 

//AREA,//l,#OUTSPC 

NOHOLD 



.WRITW,. CLOSE,. EXIT 

EMT error code byte location 
Get name of file to copy 
Proceed unless error 
Point to first input filspc 
Try to open input file 
Get a new command on error 
Point to output filspc 
Put LP: in output filspc 
Point to input filspc filename 
Move file name into LP filspc 

(not necessary, but convenient) 
Skip over file extension 
Open channel to printer (spooled) 
Proceed unless error 
Close input file 
And give up 



Tell spooler to hold file until it is closed 
(must be issued before any writes to file) 



NOHOLD: 


MOV 


//SPHOLD, RO ; 




EMT 


375 ; 




CLR 


R2 ; 


6$: 


.READW 


//AREA, #0, //BUFFER, #256 . ,R2 




BCS 


NXTFIL ; 




.WRITW 


//AREA, //l , //BUFFER, #256 . , #0 




BCC 


8$ ; 




.CLOSE 


#1 ; 




BR 


GIVEUP ; 


8$: 


INC 


R2 ; 




BR 


6$ ; 


NXTFILr 


.CLOSE 


#0 ; 




.CLOSE 


#1 ; 




TST 


2(R1) ; 




BNE 


OPNFIL ; 




BR 


START ; 


AREA: 


.BLKW 


10 ; 


SPHOLD: 


.BYTE 


1,151 ; 




.WORD 


; 


HNH: 


.WORD 


1 ; 


OUTSPC : 


.BLKW 


15. ; 



Point to EMT arg block to 
Hold output until close 
Initialize block pointer 

;Copy a block from the file 
Try next file on error 

;Copy the file block to LP 
Error? 

Close print file 
Forget it 

Point to next block 
And get next block 
Close input file 
and print file 
Any input file? 
Repeat if so 
Else ask for more files 

General EMT arg block area 
EMT arg block to hold spool output 
on channel 1 until file is closed 
HNH=0 immed; HNH=1 hold til close 
Output file specs 
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INS PC: .BLKW 24. 

DEFEXT: .WORD 0,0,0,0 

BUFFER: .BLKW 256. 

.END START 



; Input file specs 

;No default file types 

;I/0 buffer area 



5.5 Use of special forms with spooled devices 

Output files directed to spooled devices are queued and held until the spooled 
device becomes free. Because of this, a special procedure is required to 
synchronize the mounting of a special form with the printing of a file that 
requires the form. 

If the first character in a file directed to a spooled device is a right square 
bracket ("]")» TSX-Plus will interpret the following one to six characters in 
the file as the name of the form on which the file should be printed. Form 
names may be from one to six characters in length and must be specified 
immediately following the initial square bracket character. The form name must 
be terminated with a carriage return, line feed. Square bracket characters are 
not significant to the spooler in any position other than the first character 
of the file. 

If a spooled file does not begin with a right square bracket character, 
TSX-Plus uses the form name that was last specified by the user with a FORM 
command (see Chapter 2). If no FORM command has been issued by the user, 
TSX-Plus uses the form name "STD" for the file. 

Each time TSX-Plus selects a file to be printed on a spooled device, it first 
looks for a waiting file that requires the form currently mounted on the 
spooled device. If several such files are available, the oldest one is 
started. If no file can be found that requires the currently mounted form, 
TSX-Plus selects the oldest file requiring a different form and issues a form 
mount request. The message appears on the the operator's terminal as: 

"Mount 'XXXXXX' form on dd" 

where "XXXXXX" represents the form name and "dd" is the spooled device. The 
terminal to which the message is directed is the one declared as the operator's 
console when the TSX-Plus system was generated. 

Once the form mount request message is sent, the spooler for the device 
requiring the new form is suspended. In order to restart the spooler the 
operator must issue a SPOOL-FORM or SPOOL-LOCK command. These commands tell 
the spooler that a particular form has been mounted and is ready for use. The 
operator does not have to mount the form called for in the form mount request. 
He may mount any form he desires, in which case TSX-Plus will search for a 
spool file that needs the form actually mounted. 

The SPOOL-FORM and SPOOL-LOCK commands are both used by the operator to 
indicate which form has been mounted; however, there is a difference in the 
effect of the two commands. After processing all files that need the currently 
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mounted form, TSX-Plus checks for files requiring a different form. If there 
are any, it checks to see if the current form was mounted using a SPOOL-FORM or 
SPOOL-LOCK command. If a SPOOL-FORM command was used, TSX-Plus issues a form 
mount request message. If a SPOOL-LOCK command was used, TSX-Plus considers 
the current form to be locked on the printer and does not issue a form mount 
message; rather, it waits for new spool files to be created that need the 
currently mounted form. 

5.6 Form alignment procedure 

When mounting a new form it is usually necessary to verify the correct 
positioning of the form before starting production printing on the form. The 
SPOOL-ALIGN command provides this facility. 

The SPOOL-ALIGN command allows the TSX-Plus operator to specify a form 
alignment file to be printed on the indicated spooled device. Form alignment 
files are printed immediately without regard to the name of the currently 
mounted form. The SPOOL-ALIGN command may be issued repeatedly if several 
attempts are required to mount a form. 

Alignment files are created by the user and may contain any desired infor- 
mation. Typically they contain a short sample output file that matches a 
particular form. Alignment files should not contain a form name specification. 
The normal sequence of operations involving a form mount is as follows: 

1. TSX-Plus issues a form-mount request message and suspends the 
spooler. 

2. The operator mounts the desired form and issues one or more SPOOL- 
ALIGN commands to verify its positioning. 

3. Once the form is correctly positioned, the operator issues a 
SPOOL-FORM or SPOOL-LOCK command to tell TSX-Plus which form has been 
mounted . 

4. TSX-Plus begins printing the oldest file that needs the currently 
mounted form. 

The SPOOL-ALIGN command may be issued at any time, but it is typically used 
between a form-mount message and a SPOOL-FORM or SPOOL-LOCK command. 
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6. PROGRAM CONTROLLED TERMINAL OPTIONS 

6.1 Terminal input/output handling 

The terminal keyboard and screen provide the principal interface between a 
time-sharing user and the TSX-Plus operating system* TSX-Plus accepts 
characters from the keyboard, echoes them to the screen, and stores them in a 
separate buffer for each time-sharing user. Then, when a program (either a 
user written program, or a utility, or the operating system keyboard monitor) 
requests input from the terminal, characters are removed from the internal 
buffer and passed to the program. The low-level requests for input from a 
program can call for a single character (.TTYIN), or for an entire line 
(.GTLIN, .CSIGEN, .CSISPC), or for a whole block of characters (.READ). Since 
the requests for a whole line of input are most common, TSX-Plus improves 
overall efficiency for many users by retaining characters typed at the keyboard 
in an internal buffer until a special character is typed which indicates that 
the line of input is complete. This special character, which indicates that 
keyboard input is ready, is called an activation character . The standard 
activation characters are carriage return and line feed. In addition, several 
control keys will also cause immediate system response. For example, control-C 
is used to abort the execution of a running program. If the program is waiting 
for input, one control-C will cause an immediate abort. If the program is not 
waiting for input, it is necessary to type two control-C's to get the system's 
attention and abort a program. 

When a program requests terminal input, TSX-Plus puts the program in a 
suspended state until an activation character is typed. This state, in which a 
program is waiting for input, but no activation character has been typed, is 
identified as the TI state by the SYSTAT command. When characters are typed at 
the terminal, TSX-Plus responds quickly and stores them in the terminal input 
buffer for that line, then returns to process other jobs which need its 
attention. Thus, the amount of time the CPU spends processing input characters 
is kept to a minimum, and the amount of CPU time used by a program in the TI 
state is also very small. Some programs, however, request single characters 
with the .TTYIN request. Normally, these programs are treated by TSX-Plus just 
as those requesting lines of input (e.g. .GTLIN requests). That is, the job 
is suspended, input characters are stored in the terminal input buffer, and 
characters are only passed to the program after an activation character is 
typed. If a program requests a character with a single .TTYIN, the user can 
type as many characters as the terminal input buffer will hold (allocated 
during system generation), but the program will remain suspended and no 
characters are passed to the program. Then, when an activation is typed, the 
program is restored to an active state, the first character in the input buffer 
is passed to the program and processing continues. If the program requested no 
more characters, then on exit the remainder of the input buffer, including the 
activation character, would be passed to the next program (usually the keyboard 
monitor) which would try to interpret them. This may result in an invalid 
command error message. 

TSX-Plus allows the programmer a wide variety of ways to influence the normal 
input scheme outlined above. One of the most common is the use of "single 
character activation". With this technique, all characters are regarded as 
activation characters. That is, if a program requests a single character with 
a .TTYIN, then as soon as a character is typed and becomes available in the 
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input buffer, it is passed to the program and the program resumes execution. 
The standard way to request single character activation under RT-11 is by 
setting bit 12 in the user's Job Status Word (JSW). However, under TSX-Plus, 
this is not by itself sufficient to cause single character activation. The 
reason is that quite a few programs designed for a single user environment use 
this in a way that causes constant looping back and consequently "burns up" a 
large amount of processor time. In a single user environment, this is of minor 
importance since no other jobs are trying to use the processor at the same 
time. Of course, in a multi-user system, this is wasteful and should be 
avoided. Therefore, under TSX-Plus, setting JSW bit 12 is not by itself 
sufficient to initiate single character activation. It is necessary BOTH to 
set bit 12 and to issue a special command to TSX-Plus indicating that single 
character activation is actually desired. This may be done either by speci- 
fying single character activation when running the program (see the /SINGLECHAR 
switch described under the R command), or with the SET TT SINGLE command, or 
with the "S" program controlled terminal option described in this chapter. 

The situation in which a program requests single characters but none are 
available in the input buffer also receives special treatment. The single 
character input request is eventually coded as EMT 340. The .TTYIN request 
repeats this request until a character is finally obtained, whereas the .TTINR 
request supposedly permits processing to continue if no character is available. 
In fact, however, the EMT 340 call will itself suspend the job until a 
character is available from the input buffer. This is referred to as 
"stalling" on a .TTYIN. The purpose is to avoid the unnecessary looping back 
to get a character. Under RT-11, if the programmer decides not to wait for a 
character to become available, but rather proceed with execution, it is only 
necessary to set bit 6 (100 octal) in the Job Status Word. Again, some 
programs abuse this technique and would waste the system resources in a 
time-sharing environment. So, TSX-Plus requires confirmation that the user is 
aware of the extra system load that could be caused by the constant looping 
back checking for a character. This may be done either as a system command 
(SET TT NOWAIT), or with the /SINGLECHAR switch when running the program, or 
within a program by using the program controlled terminal option "U" . All of 
these methods cause TSX-Plus to honor bit 6 in the JSW. If nowait input is 
truly desired under TSX-Plus, it is necessary BOTH to set bit 6 in the JSW and 
to tell TSX-Plus to use nowait input (R [UN] /SINGLECHAR, or SET TT NOWAIT, or 
the "U" terminal option) . 

TSX-Plus allows many other ways of modifying terminal input and output for 
special circumstances. These are provided to allow maximum versatility in the 
system while still maintaining the high efficiency needed in a multi-user 
environment. The programmer communicates the need for special terminal 
handling to the system through the use of special "program controlled terminal 
options". These are described individually in the next section. 
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6.2 Program controlled terminal options 



The following table lists the functions which may be modified during program 
execution. 

Function 

Character Meaning 



A Set rubout filler character. 

B Enable VT52 & VT100 escape-letter activation. 

C Disable VT52 & VT100 escape-letter activation. 

D Define new activation character. 

E Turn on character echoing. 

F Turn off character echoing. 

H Disable virtual lines. 

I Enable lower case input. 

J Disable lower case input. 

K Enable deferred character echo mode. 

L Disable deferred character echo mode. 

M Set transparency mode for output. 

N Suspend command file input. 

Restart command file input. 

P Reset activation character. 

Q Set activation on field width. 

R Turn on high-efficiency TTY mode. 

o i.urn on singxe—cuaracter activation mou.e. 

T Turn off single-character activation mode. 

U Enable no-wait TT input test. 

V Set field width limit. 
W Turn tape mode on 

X Turn tape mode off 

Y Disable echo of line-feed after carriage-return 
Z Enable echo of line— feed after carriage— return 

These functions have a temporary effect in that they are automatically reset to 
their normal values when a program exits to the keyboard monitor. They are not 
reset if the program chains to another program until control is finally 
returned to the monitor. Some terminal options (notably high-efficiency and 
single-character modes) are incompatible with and override some other terminal 
options. 

TSX-Plus provides two methods for a running program to dynamically alter some 
of the parameter settings relating to the user's timesharing line. The 
preferred method of selecting these functions is to use the TSX-Plus EMT for 
that purpose. This is readily available from MACRO programs and an appropriate 

MACRO subroutine should be linked into jobs written in other languages. The 
form of the EMT to select program controlled terminal options is: 



EMT 



375 
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with RO pointing to the following argument block: 

.BYTE 0,152 

.WORD function-code 

.WORD argument-value 

where "function-code" is the character from the table above which selects the 
terminal option, and "argument-value" may be a third value used only with some 
of the functions. An advantage of the EMT method of selecting program 
controlled terminal options is that they may be used even when the terminal is 
in high-efficiency mode. 

Example : 



.TITLE EMTMTH 
.ENABL LC 

Demonstrate TSX-Plus program controlled terminal options using 
the EMT method. 

.MCALL .GVAL, .PRINT, .EXIT, .TTYIN 
.GLOBL PRTDEC 

Determine and display current lead-in char 
Default =35, but don't count on it 



;Determine current leadin character 

;Save it 

; "Current lead-in is" 

;Retrieve lead-in char value 

;Display it 



START: 


.GVAL //AREA, #-4. 




MOV R0,R1 




•PRINT #LEADIS 




MOV R1,R0 




CALL PRTDEC 




.PRINT #LEADND 


; Set 


rubout filler chara 




MOV #SETRUB,R0 




EMT 375 



1$: 



2$ 



; Point to EMT arg block to 
;Set rubout filler character 



Now demonstrate the current rubout filler character 
Back «pace is the default, which we changed to underline 

; "Enter some and delete them" 

; Point to input buffer 

;Get next char into input buffer 

;End of input (CR/LF pair)? 

;Yes, terminate input 

; Buffer overflow? 

;Get more if not 

.PRINT #THANKS 



.PRINT 


#TRYIT 


MOV 


//BUFFER, Rl 


.TTYIN 




CMPB 


R0,#12 


BEQ 


2$ 


CMP 


Rl , //BUFEND 


BLO 


1$ 
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.EXIT 



AREA: .BLKW 10 ; General EMT arg block 

SETRUB: .BYTE 0,152 ;EMT arg block to 

.WORD 'A ;Set rubout filler character 

.WORD '_ ; to underline 

TRYIT: .ASCII /Enter some characters at the prompt and then / 

.ASCII /erase them with/<15X12>/DELETE or Control-U./ 

.ASCII / They should be replaced with underlines. /<15><12>/*/<200> 

LEADIS: .ASCII /We don't care that the current lead-in char is /<200> 

LEADND: .ASCIZ /./ 

THANKS: .ASCIZ <15><12>/STOP — Thank you./ 

BUFFER: .BLKB 81. 
BUFEND: 

.END START 

When it is not practical to incorporate the EMT method of selecting program 
controlled terminal options into a program, an alternate method using a 
"lead-in" character may be used. This is conveniently done by sending a 
sequence of characters to the terminal using the normal terminal output 
operations of the language. Examples are the FORTRAN TYPE, COBOL-Plus DISPLAY, 
BASIC PRINT, and Pascal WRITE statements. Program controlled terminal options 
are selected by having the running program send the lead-in character immedi- 
ately followed by the function character and for some functions a third 
character defining the argument value for the function. TSX-Plus intercepts 



UUC (JJL 



iuj.xutti.ug L.uaiav.i,ci.o 



appropriate terminal option. It does not pass these intercepted characters 
through to the terminal. The default value for the lead-in character is the 
ASCII GS character (octal value 35; decimal value 29). However, the lead-in 
character may be redefined during system generation when the value conflicts 
with other uses of the system. For example, some graphics terminals use the GS 
character as either a command or parameter value. Programmers should not rely 
on the default value of the lead-in character, but may obtain the current value 
of the lead-in character from the .GVAL request with an offset of -4. Note 
that when in high-efficiency mode (set with either the RUN/HIGH switch or the 
"R" program controlled terminal option) output character checking is disabled 
and the lead-in character method of selecting program controlled terminal 
options is disabled; in this case, the lead-in character, function-code 
character, and argument value character are passed through to the terminal. 
When in high-efficiency mode, the EMT method of selecting program controlled 
terminal options is still functional. See Chapter 7 for information on turning 
high-efficiency terminal mode off by means of an EMT. 

Example: 



PROGRAM LEAD IN 

Demonstrate TSX-Plus program controlled terminal options using 
the "lead-in" character method. 
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BYTE LEADIN(2) 

INTEGER ILEAD 

EQUIVALENCE (ILEAD, LEAD IN(1) ) 
C 

C Determine and display current lead-in char 
C Default = 29, but don't count on it 
C 

ILEAD - ISPY(-4) l.GVAL with offset = -4. 

TYPE 820,LEADIN(1) ! Display the current lead-in char value 
C 

C Set rubout filler character 
C 

TYPE 800,LEADIN(1),'A','_' 
C 

C Now demonstrate the current rubout filler character 
C Back space is the default, which we changed to underline 
C 

TYPE 810 !Ask for something to be erased 

ACCEPT 830 !Wait for input before exiting 



C 



STOP 'Thank you. 



800 F0RMAT(1H+,A1,$) 

810 F0RMAT(1H0, 'Enter some characters at the prompt and then ', 

1 'erase them with'/' DELETE or Control-U.', 

1 ' They should be replaced with underlines.'/' *',$) 

820 F0RMAT(' The current value of the lead-in character is ',13,'.') 

830 F0RMAT(40H ) 

END 

The following paragraphs explain the uses of each of the program controlled 
terminal option function-codes. Any of these options may be selected by either 
the EMT method or by the lead-in character method. 

6.2.1 "A" function — Set rubout filler character. 

When a scope type terminal is being used, the normal response of TSX-Plus to a 
DELETE character is to echo backspace-space-backspace which replaces the last 
character typed with a space. TSX-Plus responds to a CTRL-U character in a 
similar fashion, echoing a series of backspaces and spaces. Some programs that 
display forms use underscores or periods to indicate the fields where the user 
may enter values. In this case it is desirable for TSX-Plus to echo backspace- 
character-backspace for DELETE and CTRL-U where "character" may be period or 
underscore as used In the form. The character to use as a rubout filler is 
specified by the argument-value with the EMT method or by the third character 
with the lead-in character method. 

6.2.2 "B" &^ "C" functions — Set VT52 & VT100 escape-letter activation. 

VT52 and VT100 terminals are equipped with a set of special function keys 
marked with arrows and other symbols. When pressed, they transmit two or three 
character escape sequences. The "B" function tells TSX-Plus to consider these 
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as activation sequences. The escape character and the letter are not echoed to 
the terminal, but are passed to the user program. The "C" function disables 
this processing and causes escape to be treated as a normal character (initial 
setting) . 

6.2.3 "D" function — Define new activation character. 



Under normal circumstances TSX-Plus only schedules a job for execution and 
passes it a line of input when an "activation" character such as carriage 
return is received. The "D" function provides the user with the ability to 
define a set of activation characters in addition to carriage return. 

The new activation character is specified by the argument- value with the EMT 
method or by the third character with the lead-in character method. The 
maximum number of activation characters that a program may define is specified 
when the TSX-Plus system is generated. 

Using this technique, any character may be defined as an activation character, 
including such characters as letters, DELETE, CTRL-U, and GTRL-G. When a 
user-defined activation character is received, it is not echoed but is placed 
in the user's input buffer which is then passed to the running program. 

By specifying CTRL-C as an activation character, a program may lock itself to a 
terminal in such a fashion that the user may not break out of the program in an 
uncontrolled manner. 

If carriage return is v specif ied as a user activation character, neither it nor 
a following line feed will be echoed to the terminal. TSX-Plus will also not 
add a line feed to the input passed to the program. 

6.2.4 "E" and "F" functions — Control character echoing. 

The "E" and "F" functions are used to turn on and off character echoing. The 
"E" function turns it on, and the "F" function turns it off. An example of a 
possible use is to turn off echoing while a password is being entered. 

6.2.5 "H" function — Disable virtual line use. 

The "H" function disables the virtual line facility for the time-sharing line. 

6.2.6 "I" and "J" functions — Control lower case input . 

The f, I li function allows lower case characters to be passed to the running 
program. The "J" function causes TSX-Plus to translate lower case letters to 
upper case letters. The SET TT [NO]LC keyboard command also performs these 
functions. 

6.2.7 "K" and "L" functions — Control character echoing . 

The "K" function causes TSX-Plus to enter "deferred" character echo mode. The 
"L E1 function causes TSX-Plus to enter immediate character echo mode. Any 
characters in the input buffer which have not been echoed when the "L" function 
is selected will be immediately echoed. See the description of the SET TT 
[NO] DEFER command for an explanation of deferred echo mode. 
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6.2.8 "M" function — Set transparency mode of output. 

If transparency mode is set, TSX-Plus will pass through each transmitted 
character without performing any special checking or processing. Transparency 
mode allows the user's program to send any 7-bit character to the terminal. 
Note that once transparency mode is set on, TSX-Plus will no longer recognize 
the lead-in character (octal 35, which means a program control function 
follows). The only way to turn off transparency mode is to exit to KMON. 

6.2.9 "N" and "0" Functions — Control command file input . 

When a command file is being used to run programs (see Chapter 3), input which 
would normally come from the user's terminal is instead drawn from the command 
file. Occasionally, it is desirable to allow a program running from a command 
file to accept input from the user's terminal rather than the command file. 
The "N" function suspends input from the command file so that subsequent input 
operations will be diverted to the terminal. The "0" function redirects input 
to the command file. These functions are ignored by TSX-Plus if the program is 
not being run from a command file. 

6.2.10 "P" function — Reset activation character. 

The "P" function performs the complement operation to the "D" function. The 
"P" function is used to remove an activation character that was previously 
defined by the "D" function. The character to be removed from the activation 
character list is defined by the argument-value with the EMT method or by the 
third character with the lead-in character method. 

Only activation characters that were previously defined by the "D" function may 
be removed by the "P" function. 

6.2.11 "Q" function — Set activation on field width. 

The "Q" function allows the user to define the width of an input field so that 
activation will occur if the user types in as many characters as the field 
width, even if no activation character is entered. The field width is 
specified by the ASCII code value of the argument-value with the EMT method or 
of the third character with the lead-in character method. If an activation 
character is entered before the field is filled, the program will be activated 
as usual. Each time activation occurs the field width is reset and must be set 
again for the next field by reissuing the "Q" function. For example, the 
following sequence of characters could be sent to TSX-Plus to establish a field 
width of 43 characters: "<lead-in>Q+" . Note that the character "+" has the 
ASCII code of 053 (octal) which is 43 decimal. 

6.2.12 "R" function — Turn on high-efficiency terminal mode. 

The "R" function causes TSX-Plus to place the line in "high efficiency" 
terminal mode. The effect of this is to disable most of the character testing 
overhead that is done by TSX-Plus as characters are transmitted and received by 
the line. Before entering high-efficiency mode the program must declare a 
user-defined activation character that will signal the end of an input record. 
Once a program has entered high-efficiency mode, characters sent to the 
terminal are processed with minimum system overhead. For example, tab 
characters are not expanded to spaces. Also, TSX-Plus does not check to see if 
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the character being sent is the TSX-Plus terminal control "leadin" character. 
This means that the lead-in character method may not be used to control 
terminal options until the program exits or the EMT to turn off high efficiency- 
mode is used (see Chapter 7). Characters received from the terminal are passed 
to the program with minimum processing: they are not echoed; and control 
characters such as DELETE, control-U, control-C, control-W and carriage-return 
are all treated as ordinary characters and passed directly to the program. 
High-efficiency mode terminal I/O is designed to facilitate machine-to-machine 
communication; it is also useful for dealing with buffered terminals that 
transmit a page of information at a time. 

6.2.13 "S" function — Turn on single-character activation mode. 

The "S" function causes TSX-Pius to allow a program to do single-character 
activation by setting bit 12 in the Job Status Word. Normally TSX-Plus stores 
characters received from the terminal and only activates the program and passes 
the characters to it when an activation character, such as carriage-return, is 
received. It does this even if bit 12 is set in the Job Status Word, which 
under RT-11 causes the program to be passed characters one-by-one as they are 
received from the terminal. The "S" function can be used to cause TSX-Plus to 
honor bit 12 in the Job Status Word. If JSW bit 12 is set and the program is 
in single-character activation mode, TSX-Plus passes characters one-by-one to 
the program as they are received and does not echo the characters to the 
terminal. The /SINGLECHAR switch for the R[UN] command and the SET TT SINGLE 
command can also be used to cause TSX-Plus to honor JSW bit 12. Since the 
high-efficiency mode implies certain terminal characteristics (such as buffered 
input and no echo), it is not possible to override these inherent modes by 
using other function codes. 

6.2.14 "T" function — Turn off single-character activation mode. 

The "T" function is the complement of the "S" function. It turns off single- 
character activation mode. 

6.2.15 "U" function — Enable non-wait TT input testing. 

The "U" function causes TSX-Plus to~~ allow a program to do a .TTINR EMT that 
will return with the carry bit set if no terminal input is pending. Normally 
TSX-Plus suspends the execution of a program if it attempts to obtain a 
terminal character by doing a .TTINR EMT and no input characters are available. 
It does this even if bit 6 of the Job Status Word is set, which under RT-11 
would enable non-blocking .TTINR's. This is done to prevent programs from 
burning up CPU time by constantly looping back to see if terminal input is 
available. The "U" function causes TSX-Plus to honor bit 6 in the Job Status 
Word and allows a program to do a .TTINR to check for pending TT input without 
blocking if none Is available. The SET TT NOWAIT command and the /SINGLECHAR 
switch for the R[UN] command also perform this function. Because the single 
character terminal option determines several terminal operating modes (such as 
no echo and transparent input), it is incompatible with other terminal 
functions which would conflict with the implied single-character operation. 
See the description of special terminal mode in the RT-11 Programmer's 
Reference Manual. 
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6.2.16 "V" function — Set field width limit. 



The "V" function is used to set a limit on the number of characters that can be 
entered in the next terminal input field. Once the "V" function is used to set 
a field limit, if the user types in more characters to the field than the 
specified limit, the excess characters are discarded and the bell is rung 
rather than echoing the characters. An activation character still must be 
entered to complete the input. The field width is specified by the ASCII code 
value of the argument-value with the EMT method or of the third character with 
the lead-in character method. The field size limit is automatically reset 
after each field is accepted and must be re-specified for each field to which a 
limit is to be applied. Note the difference between the "Q" and "V" functions. 
The "Q" function sets a field size which causes automatic activation when the 
field is filled; the "V" function sets a field size which causes characters to 
be discarded if they exceed the field size. 

6.2. 17 "W" and "X" functions — Control tape mode. 

The "W" function turns on "tape" mode and the "X" function turns it off. 
"Tape" mode can be used when a line is connected to a paper tape, cassette 
tape, floppy disk or other device that responds to X-ON/X-OFF characters to 
start and stop transmission. Turning on tape mode has three effects: 

1) TSX-Plus sends an X-OFF character (CTRL-S) to the terminal when the terminal 
input buffer fills to the point that only 10 free character positions remain; 

2) TSX-Plus sends an X-ON character (CTRL-Q) to the terminal when a program 
begins waiting for input from the line and an X-OFF has been sent previously; 

3) line-feed characters are ignored unless line-feed is declared to be a 
user-defined activation character — this is done so that each line of input 
may be terminated by both a carriage-return and a line-feed. The SET TT 
[NO] TAPE keyboard command may also be used to control tape mode. 

6.2.18 "Y" and "Z" functions — Control line-feed echo. 

The "Y" function is used to disable the echoing of a line-feed character when a 
carriage-return is received. Normally, when TSX-Plus receives a carriage- 
return character, it echoes carriage-return and line-feed characters to the 
terminal and passes carriage-return and line-feed characters to the program. 
The "Y" function alters this behavior so that it only echoes carriage-return 
but still passes both carriage-return and line-feed to the program. This 
function can be used to advantage with programs that do cursor positioning and 
which do not want line-feed echoed because it might cause the screen display to 
scroll up a line. The "Z" function restores the line-feed echoing to its 
normal mode. 
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TSX-Plus provides several system service calls (EMTs) in addition to those 
compatible with RT-li. In order to take advantage of the special features of 
TSX-Plus, programs written to run under both TSX-Plus and RT-11 should check to 
see if they are under TSX-Plus. This chapter describes the preferred method of 
checking and goes on to describe several of the special EMTs provided by 
TSX-Plus. EMTs which relate specifically to features described elsewhere in 
this manual are included in the appropriate chapters. 

7. 1 Determining if a. job is running under TSX-Plus 

In cooperation with Digital Equipment Corporation, a bit has been allocated in 
the RT-11 sysgen options word at fixed offset 372 into the RMON. The high 
order bit (bit 15; mask 100000) of this word will be set (1) if the current 
monitor is TSX-Plus version 5.0 or later. This bit will be clear if the 
monitor is any version of RT-11. Testing this bit is the preferred method of 
determining if a job is running under TSX-Plus. However, if a program is 
expected to also be used under older versions of TSX-Plus, then an alternative 
method is necessary. For older versions of TSX-Plus, first issue the .SERR 
request to trap invalid EMT requests and then issue the TSX-Plus EMT to 
determine the time-sharing line number. If the job is running under RT-11, 
this EMT will be invalid and the carry bit (indicating an error) will be set on 
return. If the job is running under TSX-Plus, then the EMT will return without 
error and the line number will be in R0. 

Example: 

.ENABL LC 

Demonstrate preferred method of determining whether job is 
running under TSX-Plus or RT-11 

.MCALL .PRINT, .EXIT,. SERR, .HERR 

JSW = 44 ;Job Status Word address 

RMON = 54 ; Pointer to base of RMON 

SYSGEN = 372 ; Index into RMON for sysgen features 

START: .PRINT #UNDER ; "Running under" 

This is the preferred method, but will not work prior to 
TSX-Plus version 5.0 

; Point to base of RMON 

;See if running under TSX-Plus 

; Branch if running under RT-11 

This is the old method, but will work correctly with 
all versions of TSX-Plus 

.SERR ;Trap invalid EMT error 
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MOV 


RM0N,R1 


TST 


SYSGEN (Rl) 


BPL 


RT11 



TSX-Plus EMTs 



RT11: 



TSXLN: 

UNDER: 

TSXPLS: 

NOTPLS: 



MOV 
EMT 
BCS 



#TSXLN,R0 

375 

RT11 



.PRINT #TSXPLS 
.EXIT 

.HERR 

.PRINT //NOTPLS 

.EXIT 



; Point to EMT arg block to 

; Determine TSX-Plus line number 

; Branch if running under RT-11 

: "TSX-Plus" 



;Reset SERR trap 
; "RT-11" 



.BYTE 0,110 

.NLIST BEX 

.ASCII /Monitor is /<200> 

.ASCIZ /TSX-Plus./ 

.ASCIZ /RT-11./ 

.END START 



;EMT arg block to get line number 



7^2 Determining the TSX-Plus line number 

The following EMT will return in R0 the number of the line to which the job is 
attached. Physical lines are numbered consecutively starting at 1 in the same 
order as specified when TSX-Plus is generated. Detached job lines occur next 
and virtual lines are numbered last. 

The form of the EMT is: 

EMT 375 
with R0 pointing to the following argument area: 

.BYTE 0,110 

Example : 

.TITLE LNTT 
.ENABL- L€ 

; What TSX line number is this terminal attached to? 
; And what type terminal does TSX-Plus think it is? 

.MCALL .PRINT, .EXIT, .TTYOUT, .SERR, .HERR 

.GLOBL PRTDEC ; Subroutine to print a word in decimal 



START : . SERR 

MOV #TSXLN,R0 
EMT 375 



;Are we under TSX-Plus? 
;Stop error aborts 
;Set up EMT request to 
;Get TSX-Plus line number 
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BCS 


NOTTSX 




MOV 


RO,LINE 




.HERR 






.PRINT 


#LINMSG 




MOV 


LINE,RO 




CALL 


PRTDEC 




. PRINT 


//TRMMSG 




MOV 


#TTYPE,RO 




EMT 


375 




ASL 


RO 




.PRINT 


TYPE(RO) 




.EXIT 




NOTTSX: 


.PRINT 
.EXIT 


#TSXERR 


LINE: 


.WORD 





TERM: 


.WORD 





TSXLN: 


.BYTE 


0,110 


TTYPE : 


.BYTE 


0,137 



;If error, not under TSX-Plus 

;Save it 

; Enable error aborts 

; Display line number message 

; Recall line number 

; Display line number 

; Display term type message 

;Set up EMT request to 

;Get terminal type from TSX-Plus 

;Returns into RO 

; Convert to word offset 

; Print type from index into table 

;A11 done 

;Say we are not under TSX-Plus 



; Storage for TSX line number 
; Storage for TSX term type code 
;TSX line number EMT parameters 
;TSX term type EMT parameters 



; Table of pointers to TSX term type names 



LINMSG: 

TRMMSG: 

TSXERR: 

UNK: 

VT52: 

V 11UU . 

HAZEL: 

ADM3A: 

LA36: 

LA120: 

DIABLO: 

QUME: 



.EVEN 

rTAn T\ 
. WUJKJJ 

.NLIST 
.ASCII 
.ASCII 
.ASCIZ 
,ASCIZ 
.ASCIZ 

A cnr'7 

.ASCIZ 
.ASCIZ 
.ASCIZ 
, ASCIZ 
.ASCIZ 
.ASCIZ 



T-rvrrr Tim C 1 ttth 1 r\/~» tt a rrniT A t\w O a t a O £ t a "I O /~v tvta t>t r\ /vttwt« 

uwis., viji, vi j.uu,riA^.fcjJLi, AuriJA, IjAjo, u\i iu , dj.AjdjjV , ^unn 

BEX 

/TSX-Plus line number: /<200> 

<15><12>/Terminal type: /<200> 

/?LNTT-F-Not running under TSX-Plus/ 

/Unknown/ 

/VT-52/ 

I V JL A.\J\J I 

/Hazeltine/ 

/ADM3A/ 

/LA36/ 

/LA120/ 

/Diablo/ ;Diablo and Qume are equivalent 

/Qume/ ; Diablo and Qume are equivalent 



.END 



START 



7.3 Determining the terminal type 

The following EMT will return in RO a value that indicates what type 
time-sharing terminal is being used with the line. The form of the EMT is: 



of 
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EMT 375 
with RO pointing to the following argument block: 

.BYTE 0,137 

The terminal type is specified either when the TSX-Plus system is generated or 
by use of the SET TT command (e.g., SET TT VT100). The terminal type codes 
which are currently defined are listed below. The types Diablo and Qume are 
functionally equivalent. 

Terminal-type Code 



(Unknown) 





VT52 


1 


VT100 


2 


Hazel tine 


3 


ADM3A 


4 


LA36 


5 


LA120 


6 


Diablo & Qume 


7 



A type code of (zero) is returned if the terminal type is unknown. 

Example : 

See the example program LNTT in the section on determining the TSX-Plus line 
number. 

7.4 Determining or changing the user name 

When using the LOGON system access program, each user is assigned both a user 
name and a project, programmer number. TSX-Plus provides an EMT which allows 
an application program to obtain the user name or (with operator privilege) to 
change it. User names may be up to twelve characters in length. If the LOGON 
program is not used, the user name will initially be blank, although it may be 
changed to a non-blank name. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block to determine the user name: 

.BYTE 0,147 
.WORD buff-addr 

where "buff-addr" is a pointer to a 12 byte area to contain the user name which 
is returned. 

To change the current user name, RO should instead point to the following 
argument block: 
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.BYTE 1,147 
.WORD buff-add r 

where "buff-addr" is a pointer to a 12 byte area containing the new user name. 
Operator privilege is required to change the user name. If changing the user 
name is attempted without operator privilege, the the name will not be changed 
and the carry bit will be set on return. 

Example: 

.TITLE GSUNAM 
.ENABL LC 

; Demonstrate TSX-Plus EMT to get/set user name 

ERRBYT - 52 ;EMT error code location 



.MCALL .PRINT, .EXIT 

START : . PRINT #NAME IS 

MOV #GSUNAM,R0 

EMT 375 

.PRINT #NAMBUF 

MOV #NEWNAM,NAMADD 

INCB GSUNAM 

MOV //GSUNAM, RO 

EMT 375 

BCC 1$ 

.PRINT #NOPRIV 
1$: .EXIT 



; Preface user name 

; Point to EMT arg block to 

;Get user name 

;And display it 

; Point to new user name 
;Set low bit to set name 
; Point to EMT arg block to 
;Set new user name 
;Error? 

;Must have operator privilege 



.NLIST 
GSUNAM: .BYTE 
NAMADD: .WORD 
NAMBUF: .BLKW 
.WORD 
.ASCII 
.ASCII 
.ASCIZ 
.END 



NEWNAM: 
NAMEIS: 
NOPRIV: 



BEX 

0,147 

NAMBUF 

6 



/CHAUNCY 



;EMT arg block to get user name 
; Pointer to receive area 
;Six word name area (12 bytes) 
;Make it ASCIZ 
/ ;The new name (12 bytes) 

/Your current user name is: /<200> 

/Operator privilege necessary to set user name./ 

START 



7.5 Controlling the size of a job 

Under RT-11, the .SETTOP EMT is used to set the top address of a job. The 
TSX-Plus .SETTOP EMT does not actually alter the memory space allocated to a 
job but simply checks to see if the requested top of memory is within the 
region actually allocated to the job and if not returns the address of the top 
of the allocated job region. The TSX-Plus .SETTOP EMT was implemented this way 
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because many programs written for RT-11 routinely request all of memory when 
they start regardless of how much space they actually need. 

The memory space actually allocated for a job can be controlled by use of the 
"MEMORY" keyboard command or by use of the EMT described below. The memory 
size specified by the most recently executed MEMORY keyboard command is 
considered to be the "normal" size of the job. The EMT described here can be 
used to alter the memory space allocated to a job but the job size reverts to 
the normal size when the job exits or chains to another program. 

The form of the EMT used to change a job's size is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0,141 
.WORD top-address 

where "top-address" is the requested top address for the job. If this address 
is larger than the allowed size of a job, the job will be expanded to the 
largest possible size. On return from the EMT, RO contains the address of the 
highest available word in the program space. 

A program is not allowed to change its size if it was started by use of the 
"RUN/DEBUG" command or the system was generated without allowing program 
swapping. In either of these cases the EMT operates exactly like a .SETTOP 
request (i.e., the requested program top address will not be allowed to exceed 
the normal program size). 

See also the description of the SETSIZ program in Appendix A for information 
about how the default memory allocation for a program can be built into the SAV 
file for the program. 

Example : 

See the example program CKSTAT in the section on determining job status 
information. 

7.6 Obtaining TSX~Flus system values 

The .GVAL EMT that is normally used to obtain RT-11 system values can also be 
used to obtain TSX-Plus system values. Although a simulated RMON is normally 
mapped into each job so that it may directly access fixed offsets into RMON, 
the .GVAL function is the preferred method for obtaining system values. Under 
TSX-Plus, the simulated RMON need not be mapped into a job's virtual address 
space (see Chapter 8). The .GVAL EMT will still function correctly even if 
RMON is not mapped into the job. In addition to the positive offset values 
which are documented for use with RT-11, the following negative offset values 
may be used to obtain TSX-Plus system values: 
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Offset Value 



-2. Job number 

-4. "Lead-in" character used for terminal control options 

-6. 1 if privileged job; if non-privileged job 

-8. 1 if PAR 7 mapped to I/O page; otherwise 

-10. Project number job is logged on under 

-12. Programmer number job is logged on under 

-14. TSX-Plus incremental license number 

-16. Current job priority 

-18. Maximum allowed job priority 

-20. Number of blocks per job in SYrTSXUCL.TSX 

-22. Job number of primary line (0 for primary line) 

-24. Name of system device (RAD50) 

(may not correspond to current SY assignment) 

-26. Minimum fixed-high-priority value 

-28. Maximum fixed-low-priority value 

As with the standard .GVAL function, the system values are returned in R0, 

Example : 

.TITLE TSGVAL 
.ENABL LC 

; Demonstrate usage of .GVAL with both positive (RT-I1) 
; and negative (TSX-Plus) offsets 

.MCALL .GVAL, .PRINT, .EXIT 



. GLOBL PRTDEC 
.GLOBL PRTR50 



SYSGEN = 372 



START: 



.GVAL 


//AREA, //SYSGEN 


TST 


R0 


BPL 


9$ 


.PRINT 


//LICENS 


.GVAL 


//AREA, #-14. 


CALL 


PRTDEC 


. PRINT 


//SYSTEM 


.GVAL 


//AREA, #-24. 


CALL 


PRTR50 


.PRINT 


//JOBNUM 


.GVAL 


#AREA,//-2 


CALL 


PRTDEC 


.GVAL 


//AREA, #-22. 


TST 


R0 


BEQ 


9$ 



; Subroutine to print a word in decimal 
; Subroutine to print a RAD50 word 

;RM0N offset to sysgen options word 

Examine system options word 

See if we are running TSX-Plus 

Exit if not 

"License # is" 

Obtain last 4 digits of license // 

And display it 

"Started from" 

Get system device 

And display it 

"Job // is" 

Get TSX-Plus job number 

Display the job number 

See if this is the primary line 

if primary 

Done if so 
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9$: 

AREA: 

LICENS 
SYSTEM 
JOBNUM 
VIRT: 



.PRINT #VIRT 
.EXIT 



;Else say virtual job 



;2 word EMT arg area 



.BLKW 2 

.NLIST BEX 

.ASCII /TSX-Plus license number /<200> 

.ASCII <15><12>/TSX-Plus started from /<200> 

.ASCII /:/<15><12>/TSX-Plus line number /<200> 

.ASCII / (This is a virtual line)/<200> 



.END 



START 



7.7 Determining job status information 

The information about various jobs on the system which is displayed by the 
SYSTAT command may also be obtained by application programs. An EMT is 
provided with several subfunctions to obtain the desired job status infor- 
mation. This EMT may obtain information about any job on the system, not only 
itself. The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument block: 

.BYTE 0,144 

.BYTE line-#, sub-function 

.WORD buf-address 

where "line-//" is the number of the time-sharing line about which information 
is to be returned. Line numbers are in the range 1 up to the highest valid 
line number for the system. "Sub-function" is a function code which indicates 
the type of information to be returned by the EMT (see below), "buf-address" 
is the address of the first word of a 2 word buffer area into which the 
returned value is stored. Note: some of the functions only return a single 
word value in which case the value is returned into the first word of the 
buffer area. 

If an error occurs during the execution of the EMT, the carry-flag is set on 
return and the following error codes indicate the type of error: 



Errors: 



Code Meaning 



Indicated line number is not currently logged on. 

Invalid sub-function code. 

Invalid line number (0 or higher than largest valid line number). 



Each of the sub-functions is described below: 
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Subfunction # — Check status of line* The value returned contains bit flags 
that indicate the status of the job. The following bit flags are defined: 

000001 = This is a virtual line. 

000002 = This is a detached job line. 
000100 = Job has locked itself in memory. 
000200 = Job has operator privilege. 

Subfunction #. _L ZL Get job's execution state. This subfunction returns a code 
that indicates a job's current execution state. The following code values are 
defined: 

i = Non-interactive high priority run state. 

2 = Normal priority run state. 

3 = Fixed-low-priority run state. 

4 = Waiting on input from the terminal. 

5 = Waiting for output to be written to terminal. 

6 = Doing a timed wait. 

7 = Suspended because . SPND EMT done. 

8 = Waiting for access to a shared file. 

9 = Waiting for a inter- job message. 

10 = Waiting for access to USR (file management) module. 

11 = Waiting for non-terminal 1/0 to finish. 

12 = Waiting for access to spool file. 

13 = Interactive high priority run state. 

T A = "C-I v^ ^4— V\ -i />V»— -n~v -i r\ir -i i- \t i«im o f- *a ■#- £y 

J- -T — i XACU HJ.gU ^J L. J-VJ A. J- U Jf LUU JkaU^l 

15 = Waiting for memory expansion. 

Subfunction # 2 — Determine amount of memory used by job. This function 
returns the number of 256-word blocks of memory that are currently being used 
by the job, including PLAS regions. 

This function returns the 
number of minutes that a job has been logged onto the system. 

Subfunction _# 4_ ^ Determine position of job in memory. This function returns 
the 256-word block number of the start of the memory area allocated to the job. 

Subfunction #_ 5_ ^Z. ^ et name of program being run by job. This function returns 
a 2 word value. The two words contain the RAD50 value for the name of the 
program currently being run by the job. 

Subfunction #_ 6^ ~ G et project and programmer number for job. This function 
returns a two word value. The first word contains the project number that the 
job is logged on under; the second word contains the programmer number. 
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Subfunction # 7 ~ Get CPU time used by job. This function returns a two word 
value that contains the number of clock-ticks of CPU time used by the job. The 
first word contains the high-order 16-bits of the value, the second word 
contains the low-order 16-bits. 

Subfunction _# 8^ -- Get current job execution priority. This function returns 
one word that contains the current job execution priority level (0-127). 

Example: 

.TITLE CKSTAT 
.ENABL LC 

; Demonstration of MEMTOP, JSTAT and SNDMSG EMTs of TSX-Plus 



ERRBYT = 52 
PRGNAM = 5 



;EMT error code location 

; JSTAT subfunction code to get prog, name 



.MCALL ,TWAIT,.EXIT 

START: MOV //MEMTOP, R0 ; Point to EMT arg block to 

EMT 375 ;Set job size 

;0nly works in swapping environment, otherwise behaves like .SETTOP 

CMP R0,#HILIM ;See if we got what we wanted 

BHIS AGAIN ;Go on if so 

.EXIT ;else quit (can't disp err msg from det line) 



AGAIN: MOVB 
CHECK: MOV 

EMT 

BCS 

CMP 

BNE 

CMP 

BNE 
;Send a message 
; (Each message 

MOVB 

MOV 

MOV 

EMT 

MOV 

MOV 

EMT 

MOV 

MOV 

EMT 

MOV 

MOV 

EMT 



//1,LINE 

//JSTAT, R0 

375 

ERRTYP 

BUFADD,DUNJUN 

NEXT 



;Check all lines starting with #1 

; Point to EMT arg block 

;Get name of job being run 

;Go find out what kind of error 

;Is this line goofing off? 

;No, proceed 

BUFADD+2 , DUNJUN+2 ;May be, check for sure 

NEXT ;No, proceed 

to the offending line 
must be < 88. bytes) 



LINE,Y00H00 

#MESAG1,MSGADD 

#SEND,R0 

375 

//MESAG2,MSGADD 

#SEND,R0 

375 

#MESAG3,MSGADD 

#SEND,R0 

375 

#MESAG4,MSGADD 

//SEND,R0 

375 



Who is the guilty party? 

Prepare part one of message 

Point to EMT arg block to 

Send a message to that line 

Prepare for part two of the message 

Point to EMT arg block to 

Send part 2 of message 

Prepare for part three of the message 

Point to EMT arg block to 

Send part 3 of message 

Prepare for part four of the message 

Point to EMT arg block to 

Send part 4 of message 
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NEXT: 



SLEEP: 



ERRTYP: 



2$: 

MEMTOP: 

JSTAT : 

LINE: 

SUBFUN: 

BUFADD: 
MAXLIN; 

SEND: 
YOOHOO : 
MSGADD: 
AREA: 
TIME: 



DUNJUN: 
MESAG1: 



MESAG2; 
MESAG3 : 
MESAG4 : 



INCB 

CMPB 

BGT 

BR 

.TWAIT 

BR 

CMPB 

BLT 

BEQ 

MOVB 

DECS 

BR 

.EXIT 

.BYTE 
.WORD 
.BYTE 

PVT1C 

• DIXU 

.BYTE 
.WORD 
.BLKW 
.BYTE 
.EVEN 
.BYTE 
.WORD 
.WORD 

bt vrj 

. £>JJIN-*V 

.WORD 

.WORD 

.NLIST 

.RAD50 

.ASCII 

.ASCII 

.ASCIZ 

.ASCII 

.ASCIZ 

.ASCII 

.ASCIZ 

.ASCIZ 



LINE 

LINE, MAXLIN 

SLEEP 

CHECK 

#AREA,#TIME 

AGAIN 

@#ERRBYT,#1 

NEXT 

2$ 

LINE, MAXLIN 

MAXLIN 

SLEEP 



Try next line 

Have we checked them all? 

Yes, wait awhile 

Go check the rest of the lines 

Come back in 5 minutes 

And try again 

Which error is it 

— > line not logged on, try next line 

1 — > invalid sub-function code, give up 

2 — > line > last valid line 
Largest valid line number 
should only happen first time 

Invalid code should never happen 

Might as well kill job 

Argument block for MEMTOP EMT 

Upper address limit 

Argument for JSTAT EMT 

TSX— Plus line number to be checked 

EMT subf unction 

Address of 2-word buffer for returned value 

2 word buffer to hold stat result 

Maximum number of lines under TSX-Plus 

Will be altered to max valid line # 

EMT arg block to send a message 

Destination line number 

Message to be sent 

.TWAIT arg area 

time high word 

5min * 60.sec/min * 60. ticks/sec 



0,141 
HILIM 
0,144 


PRGNAM 
BUFADD 
2 
30. 

0,127 


MESAG1 

o 

i. 



5*60. *60. 

BEX 

/DUNJUN/ 

<7><15><12> 

/********************************** /<15><12> 



;Name of illicit program 



/* 

/* 

/* 
/* 

/* 



Continued use of this system 
for game playing will result 
in loss of user privileges! ! 



*/<15><12> 
*/<15X12> 
*/<15><12> 

*/<15><12> 
*/<15><12> 



/**********************************/<! 5><12><7> 



HILIM: .END 



START 



7.8 Setting job priority 

Jobs may be assigned priority values in the range to 127 to control their 
execution scheduling relative to other jobs. The priority values are arranged 
in three groups: the fixed-low-priority group consists of priority values from 
up to the value specified by the PRILOW sysgen parameter; the fixed-high- 
priority group ranges from the value specified for the PRIHI sysgen parameter 
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up to 127; the middle priority group ranges from (PRILOW+1) to (PRIHI-1). 
following diagram illustrates the priority groups: 



The 



127 



— > 



PRIHI — > 



PRIDEF — >| 



PRILOW — > 



— > 



+ + 

Fixed 

high 

priorities 

+ 

Normal 

job 

priorities 

+ + 

Fixed 

low 

priorities 

+ 



Job scheduling is performed differently for jobs in the fixed-high-priority and 
fixed-low-priority groups than for jobs with normal interactive priorities. 
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the 
fixed-high-priority group (PRIHI to 127) execute at fixed priority values. 
That is, the priority absolutely controls the scheduling of the job for 
execution relative to other jobs. A job with a fixed priority is allowed to 
execute as long as it wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The 

fixed-low-priority group is intended for use by very low priority background 

tasks. Normal time-sharing jobs should not be assigned priorities in either of 
the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be 
used by normal, interactive, time-sharing jobs. Jobs with these assigned 
priorities are scheduled in a more sophisticated manner than the fixed-priority 
jobs. In addition to the assigned priority, external events such as terminal 
input completion, I/O completion, and timer quantum expiration play a role in 
determining the effective scheduling priority. 

When a job with a normal priority switches to a virtual line, the priority of 
the disconnected job is reduced by the amount specified by the PRIVIR sysgen 
parameter. This causes jobs that are not connected to terminals to execute at 
a lower priority than jobs that are. This priority reduction does not apply to 
jobs with priorities in the fixed-high-priority group or the fixed-low-priority 
group. The priority reduction is also constrained so that the priority of jobs 
in the normal job priority range will never be reduced below the value of 
(PRILOW+1). 

-118- 



TSX-Plus EMTs 

The following EMT can be used to set the job priority from within a program. 
The job priority can also be set from the keyboard with the SET PRIORITY 
command. The current job priority, maximum allowed priority, and fixed-high- 
and fixed-low-priority boundaries may be determined with the .GVAL request. 
See the TSX-Plus System Manager's Guide for more information on the signifi- 
cance of priority in job scheduling. The form of this EMT is: 



EMT 



375 



with RO pointing to the following EMT argument block: 

.BYTE 0,150 
.WORD value 

where "value" is the priority value for the job. The valid range of priorities 
is to 127 (decimal). The maximum job priority may be restricted by the 
system manager. If a job attempts to set its priority above its maximum 
allowed priority, its priority will be set to the maximum allowed. This EMT 
does not return an v errors ~ 

Example : 

.TITLE GSPRI 
.ENABL LC 

: Demonstrate EMT to set job priority 

. MC ALL . GVAL , . GTLIN , . PRINT , . EXIT 
.GLOBL PRTDEC 



CURPRI = -16. 
MAXPRI = -18. 



START: 



1$: 



.PRINT 


#CURIS 


.GVAL 


//AREA, #CURPRI 


MOV 


R0,R1 


CALL 


PRTDEC 


.PRINT 


#MAXIS 


.GVAL 


//AREA, //MAXPRI 


MOV 


R0,R2 


CALL 


PRTDEC 


ADD 


#10., Rl 


CMP 


R1,R2 


BLE 


1$ 


MOV 


R2,R1 


MOV 


R1,NEWPRI 


MOV 


#SETPRI,R0 


EMT 


375 


. PRINT 


//NEWIS 


.GVAL 


//AREA, //CURPRI 



GVAL offset to get current priority 
GVAL offset to get maximum priority 

"current priority is" 

Obtain current job priority in RO 

Save it 

and display it 
"maximum priority is" 
Obtain maximum allowable job priority 
Save it 

and display it 
Try to boost priority by 10 
Unless exceeds maximum 
Use 10 larger if <= maxpri 
Else use maxpri 

Set new priority in EMT arg block 
Point to EMT arg block to 
Sset new job priority 
"new priority is" 
;0btain new priority 
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CALL 
.EXIT 



PRTDEC 



AREA: .BLKW 10 
SETPRI: .BYTE 0,150 
NEWPRI: .WORD 50. 



and display it 



; General EMT arg block 

;EMT arg block to set job priority 

;New job priority goes here 



.NLIST BEX 

CURIS: .ASCII /Current job priority = /<200> 

MAXIS: .ASCII <15><12>/Maximuifi job priority = /<200> 

NEWIS: .ASCII <15><12>/- New - job priority = /<200> 

.END START 

7.9 Forcing [non] interactive job characteristics 

The following EMT can be used to cause a job to be scheduled either as an 
interactive job or as a non-interactive job. Programs which do a large amount 
of terminal input, but which are not truly interactive jobs in the usual sense, 
such as file transfer programs, should use this EMT to avoid excessive 
interference with normal interactive time-sharing jobs. This feature may also 
be selected with the R[UN]/NONINTERACTIVE command. See the TSX-Plus System 
Manager's Guide for more information on job scheduling and the significance of 
interactive vs. non-interactive jobs. 

The form of this EMT is: 



EMT 



375 



with R0 pointing to the following argument block: 

.BYTE 0,153 
.WORD mode 
.WORD 

If the value of "mode" is 0, then the job will never be scheduled as an 
interactive job. If "mode" is 1, then the job will be scheduled as other 
interactive jobs are, dependent on terminal input. 

Example : 

.TITLE NONINT 
.ENABL LC 

; Demonstrate EMT to schedule job as interactive or non-interactive 

.MCALL .TTYIN, .TTY0UT, .PRINT, .EXIT 



JSW =44 
TTSPC = 10000 



;Job Status Word address 

;TT special mode bit (single-char) 
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CTRLZ 



= 32 



START: 


MOV 


#S INGLE, RO 




EMT 


375 




BIS 


#TTSPC,@#JSW 




MOV 


#NONINT,RO 




EMT 


375 




. PRINT 


#SLOW 


1$: 


.TTYIN 






CMPB 


RO,#CTRLZ 




BEQ 


9<i 




.TTYOUT 





2$: 



3$ 



BR 



1$ 



MOV 


#1 , SELECT 


MOV 


#NONINT RO 


EMT 


375 


.PRINT 


//FAST 


.TTYIN 




CMPB 


RO,#CTRLZ 


BEQ 


4$ 


.TTYOUT 




BR 


3$ 



; ASCII CTRL-Z (move on command) 

; Point to EMT arg block to 

;Turn on single character activation 

;Finish turning on single char mode 

; Point to EMT arg block to 

; Schedule this as non-interactive job 

"May be slow now if system busy" 
Get a char 
If CTRL-Z 

TVion Tnr»iTO r»n 

Else echo it back (we have to echo 

when in single char mode) 
And repeat 

Want to be interactive now 

Point to EMT ar° block to 

Schedule this as an interactive job 

"See how much faster now" 

Get a char 

If CTRL-Z 

Then move on 

Else echo it back 

And repeat 



4$: 



TTYTT 



SINGLE: .BYTE 
.WORD 
.WORD 

NONINT: .BYTE 

SELECT: .WORD 
.WORD 
.NLIST 

SLOW: .ASCII 
.ASCII 
.ASCII 
.ASCIZ 

FAST: .ASCIZ 
.END 



;EMT arg block to set term option 
; Single char activation 

;EMT arg block to sched as [non] interactive 
; Initially make non-interactive 



0,152 

'S 



0,153 





BEX 

/Type some characters in now. If the system has several / 

/interactive jobs/<15><12> 

/response will be slow. (Control-Z to get out / 

/of this mode.)/ 

<15><12>/Try again. Response should be much better./ 

START 



7. 10 Sending a. message to another line 

The following EMT can be used to cause a message to display on another line's 
terminal. (This is a different feature than message communication channels.) 
The form of the EMT is: 
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EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,127 
.WORD line-number 
.WORD message-address 

where "line-number" is the number of the line to which the message is to be 
sent and "message-address" is the address of the start of the message text that 
must be in ASCIZ form. The message length must be less than 88 bytes. 

Example : 

See the example program CKSTAT in the section on determining 
job status information. 

7. 11 Mount a. file structure 

This EMT is used to tell TSX-Plus that a file structure is being mounted and 

that TSX-Plus should begin caching the file directory for the device. The 

effect of this EMT is the same as doing a system MOUNT keyboard command. The 
form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,134 

.WORD device-spec-address 

.WORD 

where "device-spec-address" is the address of a word containing the RAD50 form 

of the name of the device on which the file structure is being mounted. If 

there is no room left in the table of mounted devices, the carry bit is set on 
return and the error code returned is 1. 

Example: 

.TITLE MQUNT- 
,E"NABL LC 

; Demonstrate TSX-Plus EMT to "MOUNT" (do directory caching on) a device 

.GLOBL IRAD50 ;SYSLIB RAD50 conversion subroutine 

BS = 10 ;ASCII Backspace 

.MCALL . PRINT, . GTLIN, . EXIT 

START: .GTLIN //BUFFER, //PROMPT ;Ask for name of device 

MOV #R50BLK,R5 ; Point to arg block for next call 
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CALL 


IRAD50 




MOV 


//MOUNT s RO 




EMT 


375 




BCC 


START 




.PRINT 


#NOGOOD 




.EXIT 






.NLIST 


BEX 


MOUNT : 


.BYTE 


0,134 




.WORD 


DEVNAM 




.WORD 





R5GBLK: 


. WORD 


3 




.WORD 


THREE 




.WORD 


BUFFER 




.WORD 


DEVNAM 


THREE: 


.WORD 


3 


DEVNAM: 


.WORD 





BUFFER: 


.BLKB 


80. 


PROMPT : 


.ASCII 


/Name of devic< 


NOGOOD: 


.ASCIZ 


/Attempt to MOl 




.END 


START 


7.12 Dismount a 


file structure 
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; Convert ASCII device name to RAD50 

; Point to EMT arg block to 

;Mount a file structure (directory caching) 

;Ask for more if OK 

;Say it was not good 



;EMT arg block to mount a file structure 

; Pointer to RAD50 name of device 

; Required argument 

; Number of args for IRAD50 call 

; Pointer to number of chars to convert 

; Pointer to chars to convert 

;Pointer to RAD50 name of device 

;Number of chars to convert 

;RAD50 representation of device name 

;GTLIN input buffer 

device to be mounted: :/<BS><BSXBSXBS><200> 

to MOUNT too many devices. /<7> 
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particular drive. The effect of this EMT is the same as a DISMOUNT keyboard 
command. The form of the EMT is: 

EMT 375 

with R0 pointing to an argument block of the following form: 

.BYTE 0,135 

.WORD device-spec-address 

.WORD 

where "device-spec-address" is the address of a word containing the RAD50 name 
of the device to be dismounted. 



Example: 



.TITLE DISMNT 
.ENABL LC 



; Demonstrate TSX-Plus EMT to "DISMOUNT" (stop caching on) a device 



.GLOBL IRAD50 
BS = 10 

.MCALL .GTLIN 



;SYSLIB RAD50 conversion subroutine 
;ASCII Backspace 
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START: .GTLIN //BUFFER, //PROMPT ;Ask for name of device 

MOV #R50BLK,R5 ; Point to arg block for next call 

CALL IRAD50 ; Convert ASCII device name to RAD50 

MOV #DISMNT,R0 ; Point to EMT arg block to 

EMT 375 jdismount a file structure (stop caching) 

BR START ; Repeat (no errors returned) 



DISMNT: 



R50BLK: 



THREE: 
DEVNAM: 
BUFFER: 
PROMPT : 



.NLIST BEX 

.BYTE 0,135 ;EMT arg block to dismount a file structure 

.WORD DEVNAM ; Pointer to RAD50 name of device 

.WORD ; Required argument 

.WORD 3 ;Number of args for IRAD50 call 

.WORD THREE ; Pointer to number of chars to convert 

.WORD BUFFER ; Pointer to chars to convert 

.WORD DEVNAM ; Pointer to RAD50 name of device 

.WORD 3 ; Number of chars to convert 

.WORD ;RAD50 representation of device name 

,BLKB 80. ; GTLIN input buffer 

.ASCII /Name of device to be dismounted: :/<BS><BS><BS><BS><200> 



.END 



START 



7.13 Set terminal read time-out value 

This EMT can be used to specify a time-out value that is to be applied to the 
next terminal input operation. This EMT allows you to specify the maximum time 
that will be allowed to pass between the time that you issue a command to get 
input from the terminal and the time that an activation character ,is received 
to terminate the input field. You also specify with this EMT a special 
activation character that is returned as the terminating character for the 
field if the input operation times out without receiving an activation 
character from the terminal. The form of the EMT is: 



EMT 



375 



with R0 pointing to the following argument block: 

.BYTE 0,117 

.WORD time- value 

.WORD activation-character 

where "time-value" is the time-out value specified in 0.5 second units and 
"activation-character" is a single character value that is to be returned as 
the last character of the field if a time-out occurs. The time value specified 
with this EMT only applies to the next terminal input field. The time value is 
reset when the next field is received from the terminal or the time-out occurs. 
A new time-out value must be specified for each input field that is to be time 
controlled. 
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Example : 

.TITLE DUNJUN 
; Demonstrate use of terminal input time-out testing 

.MCALL .TTYOUT, .TTYIN, .EXIT, .PRINT 
START: .TTYOUT #'? 



1$: 



MOV 


#SETTTO,R0 


EMT 


375 


. TTYIN 




CMP 


R0,#<15> 


BEQ 


1$ 


CMP 


R0,#<12> 


BEQ 


START 


CMP 


R0,#'Q 


BNE 


1$ 



.PRINT //DONE 



.EXIT 

SETTTO: .BYTE 
.WORD 
.WORD 



0,117 
6*60. *2 



.NLIST BEX 
DONE: .ASCIZ /STOP - / 



; Point to EMT arg block to 
;Set terminal input time-out 
;Get a character from the terminal 
;Skip over carriage returns 

;and line feeds 
; prompt for next char 
;Should we quit? 
;No, get next char 
;Quit or time-out 

;Bye 

;EMT arg block 

;6.min * 60.sec/min * 2. half-sec-units/sec 

;Activation character on time— out 



.END 



START 



See also the example program CKTTIE in the section on checking for 
input errors. 

7.14 Establishing break sentinel control 

The following EMT can be used to declare a completion routine that will be 
triggered when the "Break" key is pressed. The form of the EMT is 

EMT 375 

with R0 pointing to the following argument block: 

.BYTE 0,133 
.WORD brkchr 
.WORD cplrtn 

where "brkchr" is a user defined character that is to be declared the "Break" 
character and "cplrtn" is the address of the completion routine that is to be 
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called when the break character is received from the terminal. The specified 
completion routine will be called if the user presses either the key labeled 
"BREAK" (which transmits a long space) or types the character that is declared 
as the user-specified break character (brkchr). If no user-specified break 
character is wanted, specify the value (zero) for "brkchr" in the argument 
block and only the real "BREAK" key will be activated. Note that on some 
systems the console terminal "BREAK" key causes entry to the hardware ODT 
module and for this reason cannot be used with this TSX-Plus function. Only 
one break routine may be specified at a time for each user. If a break routine 
was previously specified, it is cancelled when a new routine is declared. If 
an address of (zero) is specified as the address of the completion routine 
(cplrtn), any previously specified break routine is cancelled and the break key 
connection is cancelled. A break routine can be used to signal an asynchronous 
request for service to a running program. A good example of its use would be 
to trigger entry to an interactive debugging program. 

Example: 



.TITLE BRKSNT 

;Demo use of break sentinel control 

•MCALL .PRINT, .TWAIT, .EXIT 
.ENABL LC 



S TART : MOV #BRKS NT , RO 
EMT 375 



; Point to argument area to 
;Establish break sentinel control 



.PRINT #MESSAG 
.TWAIT #AREA,#TIME 



; Prompt for key 

;Give the user 2 seconds to hit the break key 



TST YES 
BNE DONE 
.PRINT #NOBRK 



;Ever see a break? 
;Yes, all done 
;No, never saw it 



DONE: .EXIT 



CMPRTN: .PRINT #GOTBRK 
MOV #1,YES 
RETURN 



;Say we caught the break 

; Remember it 

;And continue 

; Completion routines are ALWAYS exited with 

;RTS PC under TSX-Plus, NEVER via RTI 



BRKSNT: .BYTE 0,133 
.WORD 
.WORD CMPRTN 



;EMT arg value block to break sentinel control 
; Declare only 'BREAK' key as break char 
;Address of completion routine to be called 
;when system notices break 



YES: 



.WORD 



;Flag for break seen 
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AREA: 



.BLKW 



TIME: .WORD 

.WORD 2.*60. 



;2 word arg area for . TWAIT 

;high word of time 
;2 sec * 60. tics/sec 



.NLIST BEX 

MESSAG: .ASCIZ /You have 2 seconds to hit the break key./ 

GOTBRK: .ASCIZ <15><12>/Break key pressed./ 

NOBRK: .ASCIZ /Never saw the break key./ 

.END START 

7. 15 Checking for terminal input errors 

The following EMT can be used to determine if any terminal input errors have 
occurred. The form of the EMT is: 

EMT 375 

with R0 pointing to the following argument block: 

.BYTE 0,116 

On return from the EMT, the carry-flag is set if an input error has occurred 
since the line logged on or since the last time a check was made for input 

1 1- J- v i. o . me u»u i_jr £>co v^jl ^ j. J. w l o uuau a.Lt; uhjiij.lui.cu Djr LiiJ-O uri-L ai.C liaLuwa 1. c 

reported errors (parity, silo-overflow, etc.) and characters lost due to 
TSX-Plus input buffer overflow. 

Example: 

.TITLE CKTTIE 
.ENABL LC 

;Check for terminal input errors 

.MCALL .PRINT, .TTYIN, .EXIT 

START: .PRINT //PROMPT ;Ask to overflow buffer 

MOV #100., Rl ;Set up counter for input loop 

MOV #SETTTO,R0 ; Point to EMT arg block to 

EMT 375 ;Set terminal time out for 0.5 sees 

;Note that this is reset after every activation character!!! 

; Start requesting characters. Input characters are stacked in the user 

;input buffer until an activation character is seen (e.g. carriage return). 

;So, all we have to do to overflow is enter more than the input buffer 

;size (defined in TSGEN either by DINSPC or with the BUFSIZ macro) 

;and type in too many before activating. 

;Use a time-out so we don't have to hit return. 

1$: .TTYIN ;Get a character from the terminal 
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CMPB R0,#37 ;Was it time-out activation char? 

BEQ TIMOUT ;Yes, exit loop 

SOB Rl,l$ ;Repeat for 100. characters 

;For a system with input buffer size=100. in TSGEN, we should be 
;able to overflow the buffer before ^e see an activation char 
TIMOUT: MOV #CKTTIE,R0 ; Point to EMT arg block to 

EMT 375 ;Check for terminal input errors 

BCS HADERR ;Say we had errors 

.PRINT #N0ERR ;Say we had no errors 

.EXIT 



HADERR: .PRINT #YESERR ;Error message 

CMP Rl,#3 ;Did we fill the buffer? 

;Note that last two chars of input buffer are reserved 
;for activation chars. Any excess input is discarded. 
T00MNY ;Yes, buffer overflow 

#HDWERR ;No, hardware error message 



BLE 
.PRINT 
.EXIT 
TOOMNY: .PRINT 
.EXIT 



//OVFERR 



;Buffer overflow message 



SETTTO: 



CKTTIE: 

YESERR: 
OVFERR: 
HDWERR: 
NOERR: 
PROMPT : 



;EMT arg block to set terminal time out 
;to 10 seconds (20 half sec units) 
;Passed as activation char on time-out 
;EMT arg block to check for input errors 



.BYTE 0,117 

,W0RD 20. 

.WORD 37 

,BYTE 0,116 

.NLIST BEX 

, ASCIZ <15><12>/There were errors during terminal input. /<7> 

, ASCIZ /(Probably input buffer overflow.)/ 

.ASCIZ /(Probably hardware error ... parity, stop bits, d$ta bits)/ 

.ASCIZ <15><12>/There were no terminal input errors./ 

.ASCIZ /Please enter more than 100 input characters and wait. . ./ 



,END 



START 



7.16 Checking for activation characters 

The following EMT can be used to determine if any activation characters have 
been received by the line but not yet accepted by the program. The form of the 
EMT is: 



EMT 



375 



with R0 pointing to the following argument block: 

.BYTE 0,123 

If there are pending activation characters, the carry-flag is cleared on return 
from the EMT; if there are no pending activation characters, the carry-flag is 
set on return from the EMT. 
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Example : 

.TITLE CKACT 
.ENABL LC 

demonstrate use of check for activation characters 



LEAD IN = 35 ; TSX-Plus program controlled terminal 

;option lead-in character 
.MCALL .PRINT, .EXIT, .GTLIN, .TWAIT, .TTYOUT 



S TART : . PR INT //PROMPT 



;Do 



; Re quest some characters 



Ai 



il 1 



/1aforra/1 onlim'ni 



1$: 



2$: 



; processing. Simulated 


MOV 


#80., Rl 


.TTYOUT 


#'. 


DEC 


Rl 


BNE 


2$ 


, TTYOUT 


#<15> 


.TTYOUT 


#<12> 


MOV 


#80., Rl 


.TWAIT 


#AREA,#TIME 


MOV 


#CKACT,R0 


EMT 


375 


BCS 


1$ 



.GTLIN #BUFFER 





CMP 


BUFFER, EX 




BNE 


1$ 




.PRINT 


#BYE 




.EXIT 




AREA: 


.BLKW 


10. 


TIME: 


.WORD 


0,1. *60. 


CKACT: 


.BYTE 


0,123 


BUFFER: 


.BLKB 


81. 




.NL1ST 


BEX 




.EVEN 




EX: 


.ASCII 


/EX/ 


PROMPT : 


.ASCII 


<LEADIN>/: 




.ASCIZ 


/Please ei 


BYE: 


.ASCIZ 


/Thank yoi 



here by .TWAIT 
;Line length counter 
;Tick, tock 
;End of line? 
;No, go on 
;New line 

; Re set line length counter 
;Wait 1 second here 
Processing ... 
; Point to EMT arg block to 
; Check for pending activation characters 
; Continue if input not complete 

;Collect the pending input 
Do something with it 
;Exit command? 
;No, continue processing 



;EMT arg block 

;l.sec * 60. tics/sec 

;EMT arg block for activation char check 

; Local input buffer 



; Disallow deferred echoing 
/Please enter up to 80 characters, then RETURN:/ 



.END 



START 
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7.17 Sending a_ block of characters to the terminal 

The following EMT can be used to efficiently send a block of characters to the 
terminal. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,114 
.WORD buffer 
•WORD count 

where "buffer" is the address of the buffer containing the characters to be 
sent and "count" is a count of the number of characters to be sent. This EMT 
is much more efficient to use than a series of .TTYOUT EMT's — it has the same 
efficiency as a .PRINT EMT but it uses a count of the number of characters to 
send rather than having the character string in ASGIZ form. 

Example: 

.TITLE TTOBLK 
.ENABL LC 

demonstration of the use of the TSX-Plus EMT to send a block of 
; characters to the terminal. 

.MCALL .EXIT 



START: 



MOV 
EMT 
.EXIT 



//TTOBLK, RO ; Point to EMT arg block to 

375 ;Send a block of chars to the terminal 



TTOBLK: . BYTE 
.WORD 
.WORD 
.NLIST 

BUFFER: .ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 

BUFEND: 

.END 



0,114 ;EMT arg block to send a block of chars 

BUFFER ; Pointer to character buffer 

<BUFEND-BUFFER> ; Count of characters to be output 

BEX 

/This EMT is used to send a block of characters / 

/to the terminal. /<15><12> 

/It is similar to .PRINT, except that it uses / 

/a count of characters/<15X12> 

/rather than a special terminating character / 

/«0> or <200»./<15><12> 



START 
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7.18 Accepting a block of characters from the terminal 



The following EMT can be used to accept all characters from the terminal input 
buffer up to and including the last activation character entered. The form of 
the EMT is: 



EMT 



375 



with RO pointing to the following argument block: 

.BYTE 0,115 
.WORD buffer 

where "buffer" is the address of the buffer where the characters are to be 
stored and "size" is the size of the buffer (number of bytes). This EMT causes 
a program to wait until an activation character is entered and then returns all 
characters received up to and including the last activation character. On 
RO contains a count of the number of characters received. If the 
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specified buffer overflows, the carry-flag is set on return. This EMT is 
substantially more efficient than doing a series of .TTYIN EMTs; it is 
particularly well suited for accepting input from page buffered terminals. 

Example: 

.TITLE TTIBLK 
.ENABL LC 

; Demonstrates the use of TSX-Plus EMT to accept a block of characters 
;from a terminal. 

.MCALL .EXIT, .PRINT, .TTYIN 



START: .PRINT //PROMPT ;Request input 

MOV //TTIBLK, RO ; Point to EMT arg block to 

EMT 375 ;Accept a block of chars from the terminal 

MOV R0,R1 ;Save input character count 
;Char count includes activation char (and LF after CR) 

BCC 1$ ;Buffer overflow on input? 

//OVFLOW ;Yes, warn user 

//BUFFER, Rl ;Point past last char in buffer 

(Rl) ;Make the input ASCIZ 

//BUFFER ;Reproduce the input 



0,115 ;EMT arg block to accept block from terminal 

BUFFER ; Start of input buffer 

<BUFEND-BUFFER> ; Length of buffer in chars (May not exceed 
;input buffer size declared in TSGEN.) 





.PRINT 


1$: 


ADD 




CLRB 




.PRINT 




.EXIT 


TTIBLK: 


• BYTE 




.WORD 




.WORD 
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.NLIST BEX 

PROMPT: .ASCIZ /70 character input buffer ready./ 

OVFLOW: .ASCIZ /?TTIBLK-F-Buff er overflow/ 

BUFFER: .ASCII /XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ ;35 chars 

.ASCII /XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ ;35 chars 

BUFEND: .ASCII /??/ ;TTIBLK will never write over these 

.END START 

7.19 Program controlled terminal options 

Programs may dynamically change various parameters related to terminal control. 
The following EMT may be used to set various program controlled terminal 
options: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,152 

.WORD function-code 

.WORD argument-value 

where "function-code" is a character which specifies which option is to be set 
or changed, and "argument-value" specifies a value used only by some options. 
See the section on program controlled terminal options earlier in this manual 
for more information on the specific options which may be selected and details 
on their effects. 

7.20 Turning high-efficiency terminal mode on and off 

TSX-Plus offers a "high-efficiency" mode of terminal operation that eliminates 
a substantial amount of system overhead for terminal character processing by 
reducing the amount of processing that is done on each character. When in 
high-efficiency mode, characters are sent directly to the terminal with minimum 
handling by TSX-Plus; operations such as expanding tabs to spaces and form- 
feeds to line-feeds are omitted as well as input processing such as echoing 
characters and recognizing control characters such as DELETE, control-U and 
control-C. The only characters treated specially on input are user-defined 
activation characters and the user-specified break character. At least one 
user specified activation character must be declared if high-efficiency mode is 
to be used. This form of terminal I/O is designed to facilitate high-speed 
machine-to-machine communication. It can be used effectively to communicate 
with buffered mode terminals. The form of the EMT used to control high- 
efficiency mode is: 
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EMT 



375 



with RO pointing to the following argument block: 

.BYTE code, 120 

where "code" is 1 to turn high-efficiency mode on and to turn it off 

Example : 

.TITLE HIEFF 
.ENABL LC 

; Demonstrate the use of TSX-Plus Hi-efficiency terminal mode 



START : 



.MCALL 


.EXIT,. PRINT 


.PRINT 


#DCLCC 


.PRINT 


//PROMPT 


MOV 


#HIEFF,R0 


EMT 


375 


MOV 


#TTIBLK,R0 


EMT 


375 


MOVB 


#15,<BUFFER-i: 


MOVB • 


#12,BUFFER(R0 


INC 


RO 


MOV 


R0,<TT0BLK+4> 


MOV 


#TTOBLK,R0 


EMT 


375 


CLRB 


HIEFF 


MOV 


#HIEFF,R0 


EMT 


375 



;Make A C an activation char 
;Ask for input 
; Point to EMT arg block to 
;Turn on hi-ef f iciency mode 
; Point to EMT arg block to 
;Accept a block of characters 
;Actual character count returned in RO 
Do something useful with the input? 
#15,<BUFFER-1>(R0) ;Replace the activation char with 
; Carriage return, line feed 
; Count LF for output 
;Set up count for output 
; Point to EMT arg block to 
; Display a block of characters 
;Get ready to turn hi-eff off 
; Point to EMT arg block to 
;Turn off hi-eff iciency mode 



.EXIT 



HIEFF: 


.BYTE 


1,120 


TTIBLK: 


.BYTE 


0,115 




.WORD 


BUFFER 




.WORD 


BUFSIZ 


TTOBLK: 


.BYTE 


0,114 




.WORD 


BUFFER 




.WORD 


BUFSIZ 


BUFFER: 


.BLKB 


82. 


BUFSIZ « 


= . - BUFFER 




.WORD 







.NLIST 


BEX 


DCLCC : 


.ASCII 


<35><-: 


PROMPT: 


.ASCII 


/Pleasi 




• A^O -LZj 


/No sp' 



;EMT arg block to turn hi-eff mode on (off) 

;EMT arg block to accept a block of chars 

;Pointer to input buffer 

; Number of chars to input 

;EMT arg block to display a block of chars 

; Pointer to buffer for output 

;Size of buffer to output 

;I/0 buffer - Cannot exceed line's I/O 

; buffer sizes declared in TSGEN 

; Spacer in case of buffer overfill 



<35X'DX3X200> ; Declare ~C as special activation char 

nter 1 line of characters ( A C ends). /<15><12> 
/No special processing or echoing will be done./ 
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.END START 

7.21 Determining number of free blocks in spool file 

The following EMT will return in RO the number of free blocks in the spool 
file. The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument area: 

.BYTE 0,107 

Example : 

.TITLE SPLFRE 
.ENABL LC 

; Demonstrate EMT to determine number of free spool blocks 



.MCALL .PRINT,. EXIT 



START: 


.PRINT 


//NUMFRE 




MOV 


//SPLFRE, RO 




EMT 


375 




CALL 


PRTDEC 




.PRINT 


//BLOKS 




.EXIT 






.NLIST 


BEX 


SPLFRE: 


.BYTE 


0,107 


NUMFRE : 


.ASCII 


/The spool 


BLOKS : 


.ASCIZ 

.EVEN 


/ free bio 


PRTDEC : 


MOV 


R1,-(SP) 




MOV 


R2,-(SP) 




MOV 


R0,R1 




MOV 


#BUFEND,R2 




MOVB 


#200, (R2) 


1$: 


CLR 


R0 




DIV 


#10., R0 




ADD 


#'0,R1 




MOVB 


R1,-(R2) 




MOV 


R0,R1 




BNE 


1$ 




.PRINT 


R2 




MOV 


(SP)+,R2 




MOV 


(SP)+,R1 



; Preface number message 

; Point to EMT arg block to 

;Determine number of free spool blocks 

; Number is returned in R0 

; Display the number 

;End of message 



;EMT arg to get // free spool blocks 



Get copy of number in Rl 

Point to end of conversion buffer 

Set end for .PRINT 

Clear high word for DIV 

Get low digit 

Convert low digit to ASCII 

Put into buffer 

Get rest of number 

Repeat for all digits 

Display the result 
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RETURN 
.BLKB 6 
BUFEND: .WORD 



.END 



START 



7.22 Set/Reset OPT activation mode 

The following EMT can be used to set TSX-Plus to activate on characters that 
are appropriate to ODT. In this mode TSX-Plus considers all characters to be 
activation characters except digits, ',', '$', and ";'. The form of the EMT 
is: 



EMT 



375 



with RO pointing to the following argument area: 

.BYTE code, 111 

where "code" = 1 to turn on ODT activation mode, and "code' 
normal mode. 

Example: 

.TITLE ACTODT 
.ENABL LC 

; Demonstrate EMT which sets ODT activation mode 



= to reset to 



.MCALL .PRINT,. EXIT 



START: 



1$: 



2$: 



.PRINT 


#ODTTYP 


MOV 


#ACT0DT,R0 


EMT 


375 


CALL 


GETLIN 


CMPB 


BUFFER, #'Q 


BNE 


1$ 


.PRINT 


#REGTYP 


CLRB 


ACTODT 


MOV 


#ACT0DT,R0 


EMT 


375 


CALL 


GETLIN 


CMPB 


BUFFER, #'Q 


BNE 


2$ 



;Say we are entering ODT activation mode 
Point to EMT arg block to 
;Set ODT activation mode 
;Get some terminal input 
;Back to regular mode? 
;No, get more lines 

I Say we are going back to regular activation 
;Make arg block into RESET mode request 
; Point to EMT arg block to 
; Reset ODT activation mode 
[Get more input 
;Want to quit? 
;No, repeat 



GETLIN: 



.EXIT 

.PRINT 

MOV 

EMT 



//PROMPT 

#TTIBLK,RO 

375 



; Re que st some input 

; Point to EMT arg block to 

;Accept a block of characters 
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CLRB BUFFER (RO) 
.PRINT //BUFFER 
RETURN 



;Make input string ASCIZ 
;And echo same string back 



;EMT arg block to SET/RESET ODT act'n mode 
;EMT arg block to get block input from term 
; Pointer to input buffer 
;Number of input chars requested 



ACTODT: .BYTE 1,111 

TTIBLK: .BYTE 0,115 

.WORD BUFFER 

.WORD 79. 

.NLIST BEX 

ODTTYP: .ASCIZ /Starting ODT activation mode./ 

REGTYP: .ASCIZ /Restoring regular activation mode./ 

PROMPT: .ASCII /?/<200> 

.EVEN 

BUFFER: .BLKB 79. ;TTIBLK input buffer 

.BYTE ;CLRB could go here on full buffer 

.END START 

7.23 Determining file directory information 

This EMT returns directory information about a file. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE chan, 145 
.WORD dblk 
.WORD rblk 

where "chan" is a channel number in the range 0-16 (octal) that is currently 
not in use, "dblk" is the address of a 4-word block containing the RAD50 file 
specification (device, file name, extension), and "rblk" is the address of a 
7-word block that will receive the information about the file. The information 
returned in "rblk" is: 



Word 
Word 
Word 
Word 
Word 
Word 
Word 



Errors: 



Size of the file (number of blocks). 

— >File not protected; 1 — >File is protected. 

File creation date (standard RT-11 date format) 

File creation time (number of 3-second units). 

Starting block number of file. 

Unused (reserved) 

Unused (reserved) 



Code Meaning 

Channel is currently in use. 

1 Unable to locate specified file. 

2 Specified device is not file structured, 
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Example : 



.TITLE FILINF 
.ENABL LC 



; Demonstrate TSX-Plus EMT to return information about a file 

.MCALL .PRINT, .EXIT, .CSISPC, .TTYOUT 
.GLOBL DSPDAT,DSPTI3 



ERRBYT = 52 



;EMT error code location 



START : 


-CSISPC 


#OUTSPC #DE' 




MOV 


//FILINF, RO 




EMT 


375 




BCC 


5$ 




MOVB 


@//ERRBYT,Rl 




ASL 


Rl 




* PRINT 


FIERR(Rl) 




.EXIT 




5$: 


MOV 


//BUFFER, RO 


10$: 


TSTB 


(R0)+ 




BNE 


10$ 




MOVB 


#200, -(RO) 




.PRINT 


#BUFFER 




.TTYOUT 


//'[ 




MOV 


FILSIZ RO 




CALL 


PRTDEC 




TST 


PRTCTD 




BEQ 


15$ 




. TTYOUT 


#'P 


15$: 


.TTYOUT 


//'] 




.PRINT 


//SPACE2 




MOV 


FILDAT,RO 




CALL 


DSPDAT 




.PRINT 


//SPACE 2 




MOV 


FILTIM,RO 




CALL 


DSPTI3 




.PRINT 


//SPACE2 




MOV 


FILLOC,R0 




CALL 


PRTDEC 




.EXIT 






.NLIST 


BEX 


FILINF: 


• BYTE 


0,145 




.WORD 


INS PC 




.WORD 


FILSIZ 


FILSIZ: 


.WORD 





PRTCTD: 


.WORD 






■0,#BUFFER ;Get file name 
; Point to EMT arg block to 
;Get information about a file 
;No error? 
;What error 
; Convert to word index 

? F. yti 1 a -f n "f 1" 



;Find the end of the file spec, 

;End? 

;No, keep looking 

;No CR,LF at end 

:File name 

'File size 

;Was file protected? 



;File creation date 
; Display date 

;File creation time (3 sec resolution) 
; Display special 3-sec time 



;File starting block // 



;EMT arg block to get file info. 

; Pointer to RAD50 file name 

; Pointer to 7 word result buffer 

;File size 

;Protected=l, unprotected=0 
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FILDAT: 


.WORD 







FILTIM: 


.WORD 







FILLOC : 


.WORD 









.WORD 


0,0 




OUTSPC : 


.BLKW 


15. 




INSPC : 


.BLKW 


24. 




DEFLT: 


.WORD 


0,0,0,0 




FIERR: 


.WORD 


CINUSE 






.WORD 


NOFILE 






.WORD 


BADDEV 




BUFFER: 


.BLKB 


81. 




SPACE2 : 


.ASCII 


/ /<200> 




CINUSE: 


.ASCIZ 


/7FILINF-F- 


-Cham 


NOFILE : 


.ASCIZ 


/7FILINF-F- 


-Can'l 


BADDEV: 


.ASCIZ 


/7FILINF-F- 


-Non-< 




.END 


START 




7.24 Setting file creation 


time 



;File date (standard format) 
;File time (special 3-sec format) 
;File starting block number 
;Pad for 2 reserved words 
;Output file specifications 
; Input file specifications 
;No default extensions 
;EMT error message table 



; Input string buffer 



Can't find file./ 
Non-directory device./ 



The time that a file is created is stored along with other directory infor- 
mation under TSX-Plus. In order to pack the time into a single word, TSX-Plus 
represents the file creation time in three second units. For example, if a 
file was created at 11:13:22, then the special time representation would be 
13467 (decimal). 

11 hr * 60 min/hr * 60 sec/min = 39600 

13 min * 60 sec/min = 780 

22 sec = 22 



40402 seconds 

40402 sec / 3 sec/unit = 13467 3-sec units 

A utility program is provided with TSX-Plus to display the creation time and 
other directory information about a file. See Appendix C for more information 
on the FILTIM utility. 

The creation date and time for a file are automatically stored by TSX-Plus in 
the directory entry for the file at the time that the file is closed after 
being created. An EMT Is provided for those unusual situations where a 
different creation time is to be specified for a file after the file is 
created. The form of this EMT is: 



EMT 



375 
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with RO pointing to the following argument block: 

.BYTE chan, 146 
.WORD dblk 
.WORD time 

where "chan" is the number of an unused channel, "dblk" is the address of a 
4-word block containing the RAD50 file specification, and "time" is the time 
value (in 3-second units since midnight) that is to be set as the creation time 
for the file. 



Errors: 



Code Meaning 

Channel is currently in use. 

1 Unable to locate specified file. 

2 Specified device is not file structured 



Example : 

.TITLE SFTIM 
.ENABL LC 

; Demonstrate TSX-Plus EMT to set file creation time 



.MCALL .PRINT, .CSISPC, .EXIT, .GTLIN 



1$: 



.GLOBL ACRTI3 



ERRBYT = 52 



START: 



2$: 



.PRINT 


//GETNAM 


.CSISPC 


#OUTSPC,#DEFLT 


.GTLIN 


#BUFFER, #GETTIM 


MOV 


//BUFFER, RO 


CALL 


ACRTI3 


BCC 


1$ 


.PRINT 


//BADTIM 


.EXIT 




MOV 


R0,NEWTIM 


MOV 


#SFTIM,R0 


EMT 


375 


BCC 


2$ 


MOVB 


@#ERRBYT,R0 


ASL 


RO 


. PRINT 


SFTERR(RO) 


.EXIT 





Subroutine to convert hh:mm:ss to special 
3-sec internal time format in RO 

EMT error code location 

Prompt for file name 
Get file name in RAD50 
Prompt for and get a time 
Point to time input buffer 
Get special time in RO 
Time error? 
Yes, incorrect format 

Save special time 

Point to EMT arg block to 

Set creation time in file 

Error? 

Yes, get error code 

Convert to word offset 

Explain 



SFTIM: 



.NLIST BEX 
.BYTE 0,146 



;EMT arg block to set file creation time 
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.WORD 


INSPC 








Pointer to RAD50 file name 


NEWTIM: 


.WORD 











Will contain new creation time 


OUTSPC : 


.BLKW 


15. 








.CSISPC output files 


INSPC : 


.BLKW 


24. 








.CSISPC input files (first is the one) 


DEFLT : 


.WORD 


0,0,0,0 








Default file extensions 


SFTERR: 


.WORD 


INUSE 








,SFTIM error message table 




.WORD 


NOFILE 










.WORD 


BADDEV 








BUFFER: 


.BLKB 


81. 






;.GTLIN input buffer - holds time hh:mm:ss 


GET NAM: 


.ASCII 


/Set creation 


time in file: /<200> 


GETTIM: 


.ASCII 


/New creal 


tion 


time: /<200> 


BADTIM: 


.ASCIZ 


/7SFTIM- 


-F- 


-Invalid time./ 


INUSE : 


.ASCIZ 


/7SFTIM- 


-F- 


-Channel in use./ 


NOFILE : 


.ASCIZ 


/7SFTIM- 


-F- 


-Can't find file./ 


BADDEV: 


.ASCIZ 


/7SFTIM- 


-F- 


-Non- 


-directory device./ 




.END 


START 
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8.1 Virtual and physical memory 

The memory space that is accessible by a job is known as the virtual address 
space for the job. Because of the architectural design of the PDP-11 computer 
which uses 16 bits to represent a virtual memory address, the maximum amount of 
virtual address space that can be accessed at one time by a job is limited to 
65,536 (64K) bytes. Thus, the virtual addresses for a job range from 000000 to 
177777 (octal). 

The actual amount of virtual address space available to a job may be as large 
as 64Kb but it may be restricted to less than this amount. The following 
factors control the size of the virtual address space available to a job: 

1) The maximum amount of memory allowed for each job as determined by 
the HIMEM system generation parameter. 

2) The amount of memory specified with the MEMORY keyboard command 
(initialized by the DFLMEM system generation parameter). 

3) The memory limit reserved in the disk file image by the SETSIZ 
program (see Appendix A). 

4) The amount of memory acquired by use of the TSX-Plus EMT that expands 
or contracts the job space. 

J-"c pujr oj.i.a.1. auuicaa apace i.ui d jrJf-±i Luiupuuci. i& uu l. iluiiucu tO 04K.D. iiie 

maximum physical address space depends on the model of PDP-11 and the amount of 
memory installed on the computer. LSI-11/23 and 11/34 computers can access up 
to 256Kb of physical memory. The 11/23-Plus, 11/73, 11/24 and 11/44 computers 
can access up to 4Mb of memory. 

The process by which an address in the job's virtual address space is trans- 
formed into an address in the physical address space is known as mapping* The 
mapping of the virtual address space for a job into the physical memory space 
assigned to the job is performed by the memory management hardware facility of 
the PDP-11 computer. This facility divides the virtual address space into 8 
sections, called pages , each of which can address up to 8Kb of memory. The 
mapping of a page of virtual address space to a page of physical address space 
is accomplished by setting up information in a page address register ( PAR ) . 
There is one page address register for each of the 8 virtual address pages. 
These registers are not directly accessible by a user job but are loaded by the 
TSX-Plus system when it starts a program, changes the size of a program, or 
switches execution between different jobs. The relationship between the 8 
pages of memory and the corresponding sections of virtual address is shown in 
the following table: 
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Page Virtual address range 



000000 - 017777 

1 020000 - 037777 

2 040000 - 057777 

3 060000 - 077777 

4 100000 - 117777 

5 120000 - 137777 

6 140000 - 157777 

7 160000 - 177777 



Because of the design of the memory management system in the PDP-11, it is not 
possible to divide the virtual address space more finely than 8 pages of 8Kb 
each. However, it is possible to map each page of virtual address space into 
any section of physical memory. (This facility allows TSX-Plus to keep 
multiple user jobs in physical memory and to switch rapidly among them by 
reloading the page address registers.) 

8.2 User virtual address mapping 

The virtual address space accessed by a job can be divided into five cate- 
gories: 

1) Normal program space which is used by instructions and data for 
programs. 

2) Simulated RMON. This is the virtual address region from 160000 to 
177777 that is mapped to a simulated RMON (RT-11 resident monitor). 

3) Extended memory windows. Programs can create regions in physical 
memory and then cause one or more pages of virtual address space to 
be mapped to the regions. 

4) Shared run-time systems. Several TSX-Plus jobs can cause a portion 
of their virtual address space to be mapped to the same area of 
physical memory. This allows several users to execute the same 
program or share common data without having to allocate a separate 
area of physical memory for each user. 

5) System I/O page. TSX-Plus real-time programs may map the system 1/0 
page into their virtual address space. 

These categories of virtual address space are discussed in the following 
sections. 
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8.3 Normal programs and virtual programs 

Programs run under TSX-Plus may be divided into two categories: normal 
programs and virtual programs . The only difference between the two types of 
programs is the manner in which TSX-Plus handles page 7 (addresses 160000 to 
177777) of the virtual address space. In the case of normal programs, page 7 
is mapped to a simulated RMON. RMON is the name of the resident RT— 11 monitor. 
When running under RT-11 this is the actual system control program. When 
running under TSX-Plus, the simulated RMON does not contain any of the 
instructions that are part of RT-11 but contains only a table that provides 
information about the system and the job. This information includes such items 
as the system version number, and information about the hardware configuration. 

i-HC: t-C-L-LO Xil U1UO UClDxC CH. C M1UWL1 dO JAXlVyiN X X ACU UXXSGLa. 111C11 pOoiLlUll Wli.ruU 

the table and their contents are documented in the RT-11 Software Support 
Manual, although not all cells are relevant to or maintained by TSX-Plus. 

The address of the base of the simulated RMON table is stored in location 54 of 
the job's virtual address space. Modern RT-11 and TSX-Plus programs should not 
directly access the RMON table but rather should use the .GVAL EMT to obtain 
values from the table. However, since some older programs and some RT-11 
utility programs directly access the RMON tables, it is mapped through page 7 
for normal programs. As a result, normal programs are restricted to using 
pages to 6 (56Kb) for their own instructions and data. 

Virtual programs are programs that do not require direct access to the 
simulated RMON table. These programs may still access the RMON values with the 
.GVAL and .PVAL EMTs . Since direct access to the simulated RMON is not needed, 

yage / xo dvo.xxa.uxc iul mc j/tugraui l.«j use; lut xl.o uwii iiiotrui-Lxuuo clllG. uaia, 

thus providing a total of 64Kb of virtual address space. A, program may 
indicate that it is a virtual program by any of the following techniques: 

1) Set bit 10 (VIRT$ — mask 2000) in the Job Status Word (location 44) 
of the SAV file. See Appendix A for information about how this bit 
can be set by use of the SETSIZ program. 

2) Use the /V LINK switch (/XM switch for the LINK keyboard command) 
which stores the RAD50 value for "VIR" in location of the SAV file. 

3) Use the TSX-Plus SETSIZ program (see Appendix A) and indicate that 
more than 56Kb of memory is to be used for the program. 

8.4 Extended memory regions 

Programs running under TSX-Plus have available the Programmed Logical Address 
Space (PLAS) facility that is provided by the RT-11XM monitor. This facility 
allows a program to allocate regions of physical memory and then create virtual 
windows that can be used to access the regions. There are 7 system service 
calls (EMTs) provided for PLAS support: 
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.CRRG — Create a region 

.ELRG — Eliminate a region 

.CRAW — Create a virtual address window 

,ELAW — Eliminate a virtual address window 

.MAP — Map a virtual window to a region 

.UNMAP — Unmap a virtual window 

.GMCX — Get information about the status of a window 

A region is an area of physical memory set aside for use by a job in addition 
to its normal job space. The .CRRG EMT is used by a program to request that a 
region be created. The size of a region is not restricted to 64Kb and may be 
as large as the physical memory installed on the system (less the space used by 
the TSX-Plus system, device handlers, tables, and the remainder of the 
program). Up to 8 regions may be created by each job. 

In order to access a region, a program must use the .CRAW and .MAP EMTs to 
create a virtual window and map the virtual window to a selected portion of the 
region. A virtual window is a section of virtual address space mapped to a 
region rather than to the normal job physical address space. Up to 8 virtual 
address windows can be created by each job. The same virtual window (i.e., the 
same range of virtual addresses) may be mapped to different regions or 
different sections of the same region at different times by use of the .MAP 
EMT. This allows a program to selectively access different sections of code or 
data in extended memory regions during the course of its execution. 

When an extended memory region is created by use of the .CRRG EMT, space is 
allocated in physical memory and in a TSX-Plus region swap file. Whenever a 
job is swapped out of memory, its extended memory regions are swapped to the 
region swap file. Space in the region swap file is allocated and deallocated 
dynamically as regions are created and eliminated. In order to create a 
region, space must be available in physical memory and in the region swap file. 

The PLAS facility is most commonly used implicitly through the virtual overlay 
and virtual array features. Using the PLAS facilities, it is possible for a 
single job to use all of the physical memory space available on a system 
(exclusive of the space used by the TSX-Plus system, handlers, tables, etc.). 
Proper use of the PLAS facilities such as with reasonable size virtual overlays 
or arrays can lead to substantial performance improvements for programs. 
Excessive use of memory space with the PLAS facility can lead to excessive job 
swapping and degraded system performance. 

8.5 Shared run- time systems 

A shared run- time system is a program or data area in physical memory that can 

be accessed by multiple TSX-Plus jobs. Shared run-time systems are somewhat 

similar to extended memory regions in that they are both allocated in extended 
memory areas and must be accessed by mapping a portion of the jobs virtual 

address space to the physical memory area. The difference is that extended 

memory regions are private to the job that creates them and may not be accessed 

by any other job. Shared run-time systems can be simultaneously accessed 

-144- 



TSX-Plus Environment 

(hence "shared") by any number of TSX-Plus jobs. Another difference between 
regions and shared run-time systems is that regions can be created dynamically 
and can be swapped out of memory; shared run-time systems are specified when 
the system is generated and reside in memory as long as the system is running. 
See Chapter 12 for more information on shared run-time systems. 

8.6 Access to system I/O page 

The system I/O page is an 8Kb section of addresses which is not connected with 
ordinary memory but rather is used to control peripheral devices and hardware 
operation. Access to the I/O page is risky in that a program can interfere 
with peripheral devices and cause system crashes. For this reason, programs do 
not ordinarily have access to the I/O page. However, a program that is running 
with TSX-Plus real-time privilege may issue a system service call to cause page 
7 (160000-177777) of the job's virtual address space to be mapped to the system 
I/O page. See Chapter 11 for more information on real-time programs. 

8. 7 VM pseudo-device handler 

While the VM handler is not actually mapped into a job's memory space, its use 
can dramatically increase job performance. The VM handler enables the use of a 
portion of physical memory as a pseudo-disk device. This permits very rapid 
access to programs and data which are placed on the VM unit. For programs such 
as compilers which heavily utilize overlay segments, a considerable speed-up 
can be achieved by loading them onto the VM device. A similar improvement for 
overlaid programs can also be obtained with the general data cache facility. 
However, when the data cache is full the least recently used blocks are lost. 
The presence of particular programs and their overlay segments in memory can be 
guaranteed by copying them to the VM pseudo-device. Another example of the 
usefulness of the VM device is with compilers which heavily use temporary work 
files. Depending on the number of write operations, which are not helped by 
general data caching, significant improvements in speed can be obtained by 
directing the work files to the VM pseudo-device* 

In order to use the VM device, it must be included in the device definitions 
during TSX-Plus system generation. An upper limit must also be placed on the 
amount of memory available to TSX-Plus. The physical memory above that 
available to TSX-Plus can then be used as a memory based pseudo-disk. If for 
some reason, it is desirable to use less than all of the memory above the top 
of TSX-Plus, the SET VM BASE command can be used to restrict the memory 
available to VM. Each time TSX-Plus is restarted, VM must be initialized just 
as you would for a new physical disk or a fresh logical subset disk. For 
example: 

INITIALIZE VM: 

Only one unit (VMO: ) is available; however, logical subset disks may be created 
within the VM pseudo-device to partition it if necessary. On initialization, 
the VM handler automatically determines the amount of memory available to it. 
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See the TSX-Plus System Manager's Guide for more information on the use of data 
caching (general and shared files) and the VM pseudo-disk. 
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9^ SHARED FILE RECORD LOCKING 

TSX-Plus allows several programs to have the same file open simultaneously. In 
order to control access to such files, TSX-Plus provides system calls to "lock" 
shared files and records within shared files. Through the record locking 
facility a program may gain exclusive access to one or more blocks in a file by 
locking those blocks. Other users attempting to lock the same blocks will be 
denied access until the first user releases the locked blocks. The TSX-Plus 
shared file facility also provides data caching on blocks being read from 
shared files. 

Note that shared file access protection is only meaningful for cooperating jobs 
requesting shared access. This scheme does not prevent other jobs from opening 
or writing to files if those jobs do not adhere to the file sharing protocol. 

The usual protocol for updating a shared file being accessed by several users 
is as follows. 

1) Open file. 

2) Tell TSX-Plus that file is "shared". 

3) Lock all blocks in file which contain desired record. 

4) Read locked blocks into memory. 

5) Make update to record. 

6) Write updated blocks to file. 

7) Unlock blocks. 

8) Repeat steps 3-7 as needed. 

9) Close file. 

DIBOL record locking procedures 

Subroutines to control record locking from within DIBOL programs are provided 

with TSX-Plus. These are discussed in Appendix B. 

Record locking from other languages 

Record locking may be interfaced to other languages with appropriate subroutine 
calls. Record locking under COBOL-Plus is built into the run-time library 
provided with COBOL-Plus. The remainder of this chapter describes the 
techniques used to control shared file access and record locking. 

9.1 Opening a_ shared file 

Before a file can be used with shared access it must be opened by using a 
standard .LOOKUP EMT. After the file has been successfully opened, the 
following EMT may be used to declare the file to be opened for shared access. 
The form of this EMT is: 

EMT 375 

with RO pointing to the following argument area: 

•BYTE chan,125 
.WORD access-code 

where "chan" is the number of the I/O channel open to the desired file and 
"access-code" is a value indicating the type of access protection desired for 
the file. The following access codes are recognized: 
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Code Protection Access 






Exclusive 


Input 


1 


Exclusive 


Update 


2 


Protected 


Input 


3 


Protected 


Update 


4 


Shared 


Input 


5 


Shared 


Update 



The access-code specifies two things: The type of access that you intend to 
make to the file (input only or update) and the type of access that you are 
willing to grant to other users of the file. There are three protection 
classes: Exclusive, Protected and Shared. Exclusive access means that you 
demand exclusive access to the file and will allow no other users to access the 
file in any fashion (input or update). Protected access means that you will 
allow other users to open the file for input but wish to prohibit any other 
users from opening the file for update. Shared access means that you are 
willing to allow other users to open the file for both input and update access. 

When this EMT is executed, TSX-Plus checks your specified protection mode and 
access type with that previously declared for the file by other users. If an 
access conflict arises because of your specified access characteristics an 
error code of 4 is returned for the EMT. If no access conflict is detected, 
your specified access code is saved with the file and will be used to check for 
conflicts with future shared access requests issued by other users. 

Normally all files that are declared to TSX-Plus using this EMT are enabled for 
use of the data caching facility (see description below). However, in some 
cases it may be desirable to suppress data caching for certain files. For 
example, sequential access files usually benefit little from data caching and 
enabling data caching for these files causes the data cache buffers to be used 
non-product ively when they could be providing a better service for other types 
of files. To disable data caching for a file set bit 8 (octal 400) in the 
access-code word. When shared access is declared with bit 8 set, new data is 
not brought into the data cache when the file is read. However, if the data 
being read is already stored in the cache because of a read by another user, it 
is used. When data being written to a file is currently stored in the cache, 
the data in the cache is updated even if the file is declared to be non-cached. 

It is possible to have several channels simultaneously open to different shared 
files. The exact number of channels that can be open to shared files and the 
total number of shared files that may be opened are specified when the TSX-Plus 
system is generated. 

Once all access to a shared file is completed, the I/O channel should be closed 
using the standard .CLOSE or .PURGE EMT's. See the next section for infor- 
mation about saving the status of a channel that has been opened to a shared 
file. 
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The error codes that can be returned by this EMT are listed below: 

Errors: 

Code Meaning 



1 
2 
3 
4 

Example : 



Channel has not been opened to a file. 
Too many channels opened to shared files 
Too many shared files open. 
File protection-access conflict 



.TITLE SHARED 
.ENABL LC 



This program cooperates with the example program (SHARE2) in the 
following section to demonstrate shared file access protection. 

.MCALL .PRINT, .GTLIN, .TWAIT, .EXIT, .READW 

.MCALL .LOOKUP, .CLOSE, .SAVE STATUS, .REOPEN, .PURGE 



ERRBYT =52 
EXUP = 1. 
PRIN = 2. 
BUFSIZ = 256. 



;EMT error byte 

; Shared file access code: Exclusive, Update 

;Shared file access code: Protected, Input 

; Number of words in a disk block 



START: .LOOKUP #AREA,//0,#SHR1 ;Open SHRl.DAT 



1$: 



2$: 



3$: 



4$: 



BCC 

.PRINT 
• EXIT 
MOV 
MOV 

EMT 

BCC 

JMP 

.READW 

BCC 

.PRINT 

.EXIT 

.PRINT 



1$ 
#LKPERR 



; Branch if OK 
;Lookup error message 



#EXUP,<SHRFIL+2> ;Set Exclusive, Update access 
#SHRFIL,R0 ; Point to EMT arg block to 

jij ,1/ccxcii.c 01IK.-L . utn.1. as <x ouculcu nxc 

;with Exclusive and Update access 
2$ ; Branch if sharing OK 

EMTERR ;Explain the error and quit 

//AREA, #0, //BUFFER, #BUFSIZ,#0 ;Read block of SHRl.DAT 
3$ ;Branch if read OK 

//RDWERR ;Say there was a read error 



//BUFFER 



; Print out the file (must have or 200 byte) 



.SAVESTATUS #AREA,//0, //BL0K1 ;Save channel status for reuse 



BCC 

.PRINT 

.EXIT 

MOV 

EMT 

. PURGE 



4$ 
//SVSERR 



#SAVSHR,R0 

375 

#0 

.LOOKUP //AREA, #0 , Z/SHR2 
BCC 5$ 



;Branch if savestatus OK 
;Savestatus error message 

;Point to EMT arg block to 
;Save shared file status 
; Purge the channel for reuse 
;0pen SHR2.DAT 
; Branch if OK 
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5$: 



.PRINT 


#LKPER2 


.EXIT 




MOV 


//PRIN,<SHRFIL+2> 


MOV 


#SHRFIL,R0 


EMT 


375 


BCC 


6$ 


JMP 


EMTER2 


.READW 


//AREA, #0, //BUFFER 


BCC 


7$ 


.PRINT 


//RDWER2 


.EXIT 




.PRINT 


//BUFFER 


.PRINT 


//PROMPT 


.TWAIT 


//AREA, //TIME 


.PURGE 


#0 


.GTLIN 


//BUFFER, //PRMPT2 



;Say bad lookup on SHR2 



Point to EMT arg block to 
Declare SHR2.DAT as a shared file 
Branch on no error 
Say error on SHR2 sharing 

6$: .READW //AREA, #0, //BUFFER, //BUFSIZ, #0 ;Read block of SHR2.DAT 

Branch if read OK 
Say read error on SHR2 
.EXIT 

7$: .PRINT //BUFFER ;Print out the contents (1 line, null filled) 

Say it's time to try companion program 
Wait 30 seconds to run other program 
Now, release SHR2 
Wait for return from virtual line 

;This job will be suspended for output while gone to virtual line 



EMTER2: 
EMTERR: 



. REOPEN //AREA, #0 , //BL0K1 
.READW //AREA, #0, //BUFFER 

//BUFFER 

#0 



.PRINT 

.CLOSE 

.EXIT 

MOV 

M0VB 

DEC 

ASL 

.PRINT 

.PRINT 

.EXIT 



//SHR2NM,FILNUM 

@//ERRBYT,R0 

R0 

RO 

SHRERR(RO) 

FILNUM 



And get SHR1 back 

//BUFSIZ, #1 ;Read in second block of SHR1 
And print it to prove status was saved 
Release SHR1 

Point to alternate file error 

Get the error type 

Zero offset 

Convert to word offset 

Print the appropriate error message 

And the file name 



;EMT arg block area 
; Saves tatus area for SHR1.DAT 
;File name for error message 
;30.sec * 60. tics/sec 
;Pointer to EMT error messages 



AREA: .BLKW 10 

BL0K1: .BLKW 5 

FILNUM: .WORD SHR1NM 

TIME: .WORD 0,30. *60. 

SHRERR: .WORD N0T0PN 

.WORD XSSCHN 

.WORD XSSFIL 

.WORD AXSC0N 

.NLIST BEX 

SHR1: .RAD50 /DK SHRl DAT/ ;File descriptor for SHR1.DAT 

SHR2: .RAD50 /DK SHR2 DAT/ ;File descriptor for SHR2.DAT 

SHRFIL: .BYTE 0,125 ;EMT arg block to declare shared file 

.WORD 1 ; Exclusive Update access (GETS CHANGED) 

SAVSHR: .BYTE 0,122 ;EMT arg block to save shared file status 

N0T0PN: .ASCII /Attempt to share unopened channel/<7><200> 

XSSCHN: .ASCII /Too many channels opened to shared f iles/<7><200> 

XSSFIL: .ASCII /Too many shared files open/<7><200> 

AXSCON: .ASCII /Attempt to protect already protected shared file/<7><200> 

SHR1NM: .ASCIZ /: SHRl. DAT/ 

SHR2NM: .ASCIZ /: SHR2.DAT/ 
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LKPERR: 


.ASCIZ 


LKPER2: 


.ASCIZ 


SVSERR: 


.ASCIZ 


RDWERR: 


.ASCIZ 


RDWER2 : 


.ASCIZ 


PROMPT : 


.ASCII 




.ASCII 




.ASCIZ 


PRMPT2 : 


.ASCII 


BUFFER: 


.BLKW 



Shared File Record Locking 

/Lookup error for SHRl.DAT/<7> 

/Lookup error for SHR2.DAT/<7> 

/Error occurred attempting to save SHR1.DAT file status/<7> 

/Error occurred while reading SHRl.DAT/<7> 

/Error occurred while reading SHR2.DAT/<7> 

/Go to a virtual line and RUN SHARE2 which attempts /<15><12> 

/to share the same files (SHRl.DAT, SHR2 .DAT) ./<15><12> 

/Waiting 30 seconds /<7> 

/When you have returned, hit RETURN to continue/<200> 
BUFSIZ 



.END 



START 



See also the example program SHARE2 in the section on saving the status of a 
shared file channel. 

9.2 Saving the status of a_ shared file channel 

A standard .SAVESTATUS EMT may be used to save the status of a shared file 

channel. If this is done, all blocks that are being held locked in the file 

remain locked until the channel is reopened and the blocks are unlocked (see 
below) . 

When using a single channel number to access several shared files it is 
convenient to initially do a .LOOKUP on each file, then declare the file to be 
shared (EMT above), and then do a .SAVESTATUS. The channel being used to 
access the set of files can then be switched from one file to another by doing 
a .PURGE followed by a .REOPEN. However, before doing the .PURGE, TSX-Plus 
must be told that you wish to save the shared-file status qf the file, 
otherwise all locked blocks will be unlocked and the file will be removed from 
the shared-file list. The form of the EMT used to perform this function is: 



EMT 



J/3 



with R0 pointing to the following argument block: 

.BYTE chan, 122 

where "chan" is the I/O channel number. The effect of this EMT is to suspend 
the connection between the shared file information table and the I/O channel. 
Any blocks that are currently locked in the file remain locked until the 
channel is reopened to the file (by using a standard .REOPEN EMT). After 
saving a shared file status, the channel may be freed by using a .PURGE EMT. 
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Example: 

.TITLE SHARE2 
.ENABL LC 

; This program cooperates with the example program (SHARED) in the 
; previous section to demonstrate saving of shared file status with 
; the .SAVE STATUS EMT. 

. MCALL . LOOKUP ,. PRINT , . EXIT , . READW 
.MCALL . CLOSE,. TWAIT 



ERRBYT =52 
BUFSIZ = 256. 



START: 



1$: 



2$ 



3$: 



4$: 



5$ 



. LOOKUP #AREA , #0 , //SHRl 
BCC 1$ 

.PRINT //LKPERR 
BR 3$ 



;EMT error byte 

;Size of disk file block 

;Try to open a file which is access locked 

; Branch if OK 

;Say couldn't get the file 

;Go on to try second file 

; Point to EMT arg block to 

; Declare file for shared access 

;If got the file, branch to read it 

;Else explain why 

;Say we can't share SHRl 

; Release channel 

;Go on to next file 



//AREA, #0, //BUFFER, //BUFSIZ, #0 ;Try to read block of SHRl 
;Display it for kicks 
;Done with SHRl for the moment 



;Try to open SHR2 

; Branch if OK 

;Say we couldn't even open it 

;Go on to try SHRl again 

; Point to EMT arg block to 

; Declare file for shared access 

;Access Input, Update to show lockout 

; though we don't write in this example 

;Branch if we can share it 

; Explain why not 

;Say we will try again later 

;Wait 5 seconds and 

;Try again 



.READW //AREA, #0, //BUFFER, //BUFSIZ, #0 ;Read block of SHR2 
.PRINT //BUFFER ; Prove that we got it 

.CLOSE #0 ;Done with SHR2 



MOV 


//SHRFIL,R0 


EMT 


375 


BCC 


2$ 


CALL 


EXPLER 


.PRINT 


//INSHR1 


.CLOSE 


#0 


BR 


3$ 


.READW 


//AREA, #0, //BUFF: 


.PRINT 


//BUFFER 


. CLOSE 


#0 


.LOOKUP 


//AREA,//0,//SHR2 


BCC 


4$ 


.PRINT 


//LKPER2 


BR 


6$ 


MOV 


#SHRFIL,R0 


EMT 


375 


BCC 


5$ 


CALL 


EXPLER 


. PRINT 


//AGAIN 


.TWAIT 


//AREA, //TIME 


BR 


4$ 
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6$: 


.LOOKUP 


#AREA,#0,#SHR1 




BCC 


7$ 




.PRINT 


#LKPERR 




.EXIT 




7$: 


MOV 


#SHRFIL,R0 




EMT 


375 




BCC 


10$ 




CALL 


EXPLER 




.PRINT 


//STLLOK 




BR 


11$ 


10$: 


.READW 


//AREA, #0, //BUFF 




.PRINT 


//BUFFER 


11$: 


. CLOSE 


#0 



;Try SHR1 again 

; Branch if it worked 

;Say we couldn't do it 



; Point to EMT arg block to 

; Declare shared file 

; Branch if OK 

;And explain the error 

;Say it was still locked 

;And quit 

:,//BUFSIZ,//l ;Read in block 1 
;And display it 
;Done with SHR1 



EXPLER: 



.EXIT 

MOVB 
DEC 
ASL 
. PRINT 
RETURN 



@//ERRBYT,R0 ;Find out why can't share it 

R0 ; Convert to zero index 

R0 ;Make into word offset 

SHRERR(RO) ;Say why we couldn't get it 



AREA: 
SHRFTL; 

SHRERR: 



TIME: 

SHR1 

SHR2; 

N0T0PN: 

XSSFCH: 

XSSFOP: 

AXSCON: 

INSHR1: 

LKPERR: 

LKPER2 : 

AGAIN: 

STLLOK: 

BUFFER: 



■NLIST 

.BLKW 

, BYTE 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.RAD50 

.RAD50 

, ASCIZ 

.ASCIZ 

, ASCIZ 

•ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

T7VTT7Vr 

.BLKW 
.END 



;EMT arg block 

;EMT arg block to declare file shared 

; Access Shared, Update 

; Shared file error message pointers 



BEX 
10 

r\ tor 

U, LZ.D 
5 

NOTOPN 

XSSFCH 

XSSFOP 

AXSCON 

0,5.*60. ;5.sec * 60. tics/sec 

/DK SHR1 DAT/ ; Input file #1 name 

/DK SHR2 DAT/ ; Input file #2 name 

/Cannot share unopened file/ 

/Too many channels opened to shared files/ 

/Too many shared files open/ 

/Shared file protected by another job/ 

/On first try at SHRl.DAT/ 

/Unable to lookup SHRl.DAT/ 

/Unable to lookup SHR2.DAT/ 

/Can't access SHR2.DAT, will try again in 5 seconds/ 

/On second try at SHRl.DAT/ 



BUFSIZ 



START 



; Input read buffer 
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See also the example program SHARED in the section on opening a shared file. 

9.3 Waiting for a_ locked block 

The following EMT can be used to lock a specific block in a file. If the 
requested block is locked by another job, the requesting job will be suspended 
until the desired block becomes available. The form of the EMT is: 

EMT 375 

with RO pointing to the following area: 

.BYTE chan, 102 
.WORD block 

where "chan" is the number of an I/O channel that has previously been declared 
to be open to a shared file and "block" is the number of the block in the file 
to be locked. Other blocks in the file which were previously locked remain 
locked. The maximum number of blocks which may be simultaneously held locked 
is specified when TSX-Plus is generated. A block number of -1 (octal 177777) 
can be used to request that all blocks in the file be locked. If several users 
request the same block, access will be granted sequentially in the order that 
the requests are received. 



Errors: 



Code Meaning 



1 Channel is not open to a shared file 

2 Request to lock too many blocks in file 



Example: 

.TITLE LOCKW 
.ENABL LC 

; This program cooperates with the example program (LOCK) in the next 
; section to demonstrate shared file record locking. 

.MCALL .PRINT, .EXIT, .TWAIT, .LOOKUP, .READW, .CLOSE 

ERRBYT = 52 ;EMT error code byte 

BUFSIZ = 256. ;Words per disk block 

START: .LOOKUP #AREA,#0,#SHR1 ;0pen SHR1.DAT 

BCC 1$ ; Branch if OK 

.PRINT //LKPERR ;Say bad lookup 
.EXIT 

1$: MOV #SHRFIL,R0 ; Point to EMT arg block to 
EMT 375 ; Declare shared file 
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2$: 
3$: 



4$: 



5$: 



6$: 



8$: 
DONE: 



BCC 

MOVB 

DEC 

ASL 

. PRINT 

.CLOSE 

.EXIT 

MOV 

EMT 

; (Job i 

BCC 

CMPB 

BHI 

. PRINT 

BR 

.PRINT 

BR 

.PRINT 
.TWAIT 
MOV 
EMT 
BCC 
. PRINT 
BR 

.TWAIT 

MOV 

EMT 

BCC 

. PRINT 

.READW 

.PRINT 

.READW 

.PRINT 

BR 



3$ ; Branch if OK 

@#ERRBYT,R0 ;Get the error code 

RO ;Make zero index 

RO ;Convert to word offset 

SHRERR(RO) ; Print the error message 

#0 ;Give back the channel 



#LOCKW,R0 
375 
.3 suspended until 
5$ 

4$ 

//SFCNOP 
2$ 
//XSLKBL 

; (Defined 

//PROMPT 

#AREA,#SEC20 

//UNLOCK, RO 

375 

6$ 

#SFCN0P 

2$ " 

#AREA,//SEC10 

#CKWSHR,R0 

375 

8$ 

#CHANGD 

//AREA, #0, //BUFFER 

//BUFFER 

//AREA, #0, //BUFFER 

//BUFFER 

DONE 



Point to EMT arg block to 
Lock block of SHR1.DAT 
block available to be locked) 
Branch when block is ready 

th..' — t- _ — -._ — o 
WU-LCIl &L tUL i 

Too many blocks locked? 
Wasn't open to shared file! 
Give up 

Too many locked blocks in file 
by MXLBLK parameter in TSGEN) 
Give up 

Switch lines to attempt access 
Wait 20 seconds before unlocking 
Point to EMT arg block to 
Unlock a single block 
Branch if OK 
Wasn't shared file! 
Give up 

Wait 10 seconds for companion 
Point to EMT arg block to 
Check for writes to shared file 
If none, wrap up 
Say we have new data 
#BUFSIZ,//0 ;Get block 
Show current contents block 
#BUFSIZ,//1 ;Get block 1 
Show contents block 1 



.PRINT //NOCHNG 

, CLOSE #0 
.EXIT 



;Say nothing has changed 
;Free up channel 



.NLIST BEX 

AREA: ,BLKW 10 

SHRFIL: .BYTE 0,125 

.WORD 4 

LOCKW: .BYTE 0,102 

.WORD 



;EMT arg block area 

;EMT arg block to declare shared file 

; Access Shared, Input 

;EMT arg block to lock shared file block 

; Block number to be locked 
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UNLOCK: 

CKWSHR: 
SHRERR: 



SHR1: 

SEC20: 

SEC 10: 

NOTOPN 

XSSFCH 

XSSFOP 

AXSCON 

LKPERR 

SFCNOP 

XSLKBL 

CHANGD 

NOCHNG 

PROMPT 



BUFFER: 



.BYTE 

.WORD 

• BYTE 

.WORD 

.WORD 

.WORD 

.WORD 

.RAD50 

.WORD 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCIZ 

.EVEN 

.BLKW 



0,113 



0,121 

NOTOPN 

XSSFCH 

XSSFOP 

AXSCON 

/DK SHR1 

0,20.*60. 

0,10.*60. 



;EMT arg block to unlock shared file block 
; Block number to be unlocked 

;EMT arg block to check writes to shared file 
; Shared file error message table 



DAT/ ;File name to be shared 
;20.sec * 60. tics/sec 
;10.sec * 60. tics/sec 
/Channel not opened to shared file/<7> 
/Too many channels opened to shared files/<7> 
/Too many shared files open/<7> 
/File protection access conflict/<7> 
/Unable to open SHRl.DAT/ 

/Can't lock or unlock block not open to shared file/ 
/Can't lock so many blocks in one file/ 
/Data has been written to file. Contents follow:/ 
/Data in file is unchanged/ 

/Block in SHRl.DAT will remain locked for 20 sec/<15><12> 
/Go to another line and RUN TLOCK to test it/<7> 

BUFSIZ 



.END 



START 



9.4 Trying to lock a. block 

This EMT is similar in operation to the previous EMT: it too is used to 
request that file blocks be locked. The difference is that if the requested 
block is already locked by another user the previous EMT suspends the request- 
ing program whereas this EMT does not suspend the program but rather returns an 
error code. As above, a request to lock block #-1 is treated as a request to 
lock the entire file. If the block is available it is locked for the request- 
ing user and no error is reported. The form of this EMT is: 



EMT 



375 



with R0 pointing to. the following argument area: 



.BYTE 
.WORD 



chan,103 
block 



where "chan" is the number of the I/O channel associated with the file and 
"block" is the number of the block which is to be locked. 
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errors: 



Code Meaning 



1 
2 
3 

Example ; 



Channel is not open to a shared file. 
Request to lock too many blocks in file. 
Requested block is locked by another user, 



.TITLE 
.ENABL 



LOCK 
LC 



; ihis program cooperates with the example program (LOCKw) in the 
; previous section to demonstrate shared file record locking. 

.MCALL .PRINT, .EXIT, .WRITW, .TWAIT, .LOOKUP, .CLOSE 

ERRBYT = 52 ;Error byte address 

START: .LOOKUP #AREA, #0,#SHR1 ;Try to open SHRl.DAT 

BCC 1$ ; Branch if OK 

.PRINT #LKPERR ;Say we couldn't open 
.EXIT 



1$; 



2$ 
3$ 



4$: 

5$: 

6$: 



; Point to EMT arg block to 

,Licu<iic oii.cn.eu. illC 

; Branch if OK 

;Get error type 

; Convert to zero index 

;Make into word offset 

; Display the error type 

; Release the channel 

• Anrl o-i xro nn 

Point to EMT arg block to 

Try to unlock block 

Branch if OK 

Which error was it 

Wasn't open to share file? 

Request to open too many blocks in file? 

Block locked by another user 

Wait 3 seconds 

And try again 

Not open to shared file 

Give up 

Too many blocks locked in file 

Give up 



.WRITW //AREA,//0,//BUFFER,//BUFSIZ,//0 ; Rewrite block 
MOV #UNLALL,RO ; Point to EMT arg block to 



MOV 


#SHRFIL,RO 


mix 


i7i; 


BCC 


3$ 


MOVE 


@#ekkbYx,kO 


DEC 


RO 


ASL 


RO 


. PRINT 


SHRERR(RO) 


.CLOSE 


#0 


*EXIT 




MOV 


#LOCK,R0 


EMT 


375 


BCC 


6$ 


CMPB 


@#ERRBYT,//2 


BLO 


4$ 


BEQ 


5$ 


.PRINT 


#WAITNG 


.TWAIT 


//AREA, //TIME 


BR 


3$ 


.PRINT 


//NOPNSF 


BR 


2$ 


.PRINT 


#XSLKBL 


BR 


2$ 



-157- 



Shared File Record Locking 

EMT 375 
.PRINT //GOBACK 
BR 2$ 



AREA: 
SHR1 : 
SHRFIL: 

LOCK: 

UNLALL: 

TIME: 
SHRERR: 



SFCNOP 
XSSFCN 
XSSFOP 
AXSCON 
LKPERR 
WAITNG 

GOBACK: 
NOPNSF j 
XSLKBL: 

BUFFER: 

BUFSIZ 



BEX 

10 

/DK SHR1 

0,125 

3 

0,103 



0,101 



.NLIST 

.BLKW 

.RAD50 

.BYTE 

,WORD 

.BYTE 

.WORD 

.BYTE 

.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.ASCIZ 
.ASCIZ 
.ASCIZ 
, ASCIZ 
.ASCIZ 
.ASCII 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.EVEN 
.ASCII 
.ASCIZ 

<.-BUFFER+l>/2 
.BYTE 0,0 



DAT/ 



;Release all blocks locked by this program 
;Message: done, go back to original line 
;Done 



EMT arg block 

Name of shared file 

EMT arg block to share file on chan 

Access Protected, Update 

EMT arg block to lock block on chan 

number of block to be locked 

EMT arg block to unlock all blocks on chan 

(Only applies to blocks locked by this job) 

3. sec * 60. tics/sec 

File sharing EMT error table 



0,3.*60. 

SFCNOP 

XSSFCN 

XSSFOP 

AXSCON 

/Channel not open to file/<7> 

/Too many channels open to shared files/<7> 

/Too many shared files open/<7> 

/Shared file access conflict/<7> 

/Couldn't open SHRl.DAT/<7> 

/Requested block not available for locking/<15><12> 

/Will try again in 3 seconds/ 

/Done, log off and go back to original line/ 

/Channel not open to shared file/<7> 

/Attempt to lock too many blocks in file/<7> 

/(SHRl)This line was written by the program LOCK./ 
/ /<15><12> 

;Number of words to write 

; Safety bumper 



,END 



START 



9.5 Unlocking a_ specific block 

The following EMT is used to unlock a specific block in a file. The form of 
the EMT is: 

EMT 375 

with R0 pointing to the following argument block: 

.BYTE chan, 113 
.WORD block-number 

where "chan" is the number of the 1/0 channel opened to the shared file and 
"block-number" is the number of the block to be unlocked. 
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Errors: 

Code Meaning 

1 Specified channel not opened to a shared file 

Example : 

See the example program LOCKW in the section on waiting for a locked 
block. 

9.6 Unlocking all locked blocks in a. file 

The following EMT is used to unlock all blocks held locked in a file. The form 
of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE chan, 101 

where "chan" is the I/O channel number open to the shared file. When this EMT 

is executed all blocks previously locked by the user on the shared file are 

unlocked. Blocks locked by the user on other files are not released nor are 
blocks of the same file that are locked by other users. 

Errors: 



Code Meaning 

1 Channel is not open to a shared file. 

Example : 

See the example program LOCK in the section on trying to lock a block. 

9.7 Checking for writes to a_ shared file 

The following EMT can be used to determine if any other user has written to a 
shared file. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE chan, 121 

where "chan" is the I/O channel number opened to the shared file. If no other 
user has written to the file since the file was opened by the user issuing this 
EMT or since that last time this EMT was issued for the file, the carry-flag is 
clear on return from the EMT. 
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Errors: 

Code Meaning 

2 Some other job has written to file since last check 

This EMT is useful when data from a shared file is being held in a program 
buffer. If no other user has written to the file, then the data is still 
valid. However, if the data in the file has been re-written then it must be 
re-read. The usual sequence of operations in this situation is to first lock 
the block whose data is in the program's buffer, then do the EMT to see if the 
file has been written to. If the file has not been modified the data in memory 
is valid and can be used, otherwise the block must be re-read from the file. 

Example: 

See the example program LOCKW in the section on waiting for a locked block. 

9.8 Data caching 

Data caching is a technique provided by TSX-Plus to speed access to files. 
When TSX-Plus is generated a certain number of 512-byte buffer areas may be set 
aside for data caching. These buffer areas are part of the resident system 
data area and are not associated with any particular job. There are two kinds 
of data caching: generalized data caching; and shared-file data caching. Both 
kinds may used automatically with minimal intervention on the part of the 
programmer or operator. Generalized data caching applies to all files on 
MOUNTed devices, while shared-file data caching applies only to files which 
have been declared as shared files. Generally, only one of these types is 
selected during generation of a TSX-Plus system. The following discussion 
applies to shared-file data caching. See the TSX-Plus System Manager's Guide 
for more information on data caching. 

Each time a request is issued to read a shared file, a check is made to see if 
the blocks being read are currently stored in the data cache. If so, the data 
is moved from the cache buffer to the program buffer and no disk I/O operations 
are performed. When data in the cache buffers is accessed, a use count is 
incremented. Periodically, the use counts for all buffers is divided by two. 
If the data blocks being read are not currently in the cache, the data is read 
from the disk into the program buffer and then it is moved into the cache 
buffers with the lowest use count. 

When a write operation is done to a file that is being cached, a check is made 
to see if the data being written is currently stored in the cache. If so, the 
cache buffers are updated. In any case the data is written to the disk. In 
other words, this is a "write-through" cache; the disk file is always updated 
and caching does not improve the performance of "writes". 

All data files that are declared to TSX-Plus for shared access (using EMT 375 
with function code 125) are eligible for data block caching regardless of their 
access protection type. Data caching on a shared file may be disabled by 
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setting bit 8 (octal 400) in the access-code word of the EMT argument block 
when the file is declared for shared access. Data caching is particularly 
effective for COBOL-Plus ISAM files. 
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10. MESSAGE COMMUNICATIONS FACILITIES 

TSX-Plus provides an optional facility that allows running programs to send 
messages to each other. This message communication facility allows programs to 
send messages through named channels, check to see if messages are pending, and 
suspend execution until a message is received. TSX-Plus provides EMTs for each 
of these operations which are described below. 

10.1 Message channels 

Messages are transferred to and from programs by using TSX-Plus "Message 
Channels". A message channel accepts a message from a sending program, stores 
the message in a queue associated with the channel and delivers the message to 
a receiving program when requested. Message channels are totally separate from 
I/O channels. 

Each message channel is identified to the sending and receiving programs by a 
one to six character name. The total number of message channels is defined 
when TSX-Plus is generated. The names associated with the channels are defined 
dynamically by the running programs. A message channel is said to be "active" 
if any messages are being held in the queue associated with the channel or if 
any program is waiting for a message from the channel. When message channels 
become inactive they are released and may be reused. 

Once a message is queued on a channel, that message will remain in the queue 
until some program receives it or the TSX-Plus system is halted. A program may 
exit after queuing a message without affecting the queued message. This allows 
one program to leave a message for another program that will run later. 
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The following EMT is used to queue a message on a named channel. If other 
messages are already pending on the channel, the new message is added to the 
end of the list of waiting messages. The sending program continues execution 
after the EMT and does not wait for the message to be accepted by a receiving 
program. During processing of the EMT the message is copied to an internal 
buffer, and the sending program is free to destroy its message on return from 
the EMT. The form of the EMT is: 

EMT 375 

with R0 pointing to the following argument area: 



.BYTE 


0,104 


.WORD 


chadr 


.WORD 


msadr 


.WORD 


mssiz 



where "chadr" is the address of a six byte field containing the name of the 

message channel (ASCII with trailing blanks if the name is less than six 

characters), "msadr" is the address of the beginning of the message text, and 
"mssiz" is the message length in bytes. 
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Errors: 



Code Meaning 



All message channels are busy. 

Maximum allowed number of messages already in message queues. 
The transmitted message is too long. The message is truncated 
to maximum allowed length. 



The system manager may alter parameters during TSX-Plus generation to alle 1 
these error conditions. 

Example: 

.TITLE SNDMSG 
.ENABL LC 

; Demonstrates use of the TSX-Plus EMT to queue a message to the interproct 
; message communication facility. 

.MCALL .EXIT, .PRINT, .GTLIN 



ERRBYT 


= 52 




START: 


.GTLIN 


#MSGBUF,#MSGPRT 




MOV 


#MSGBUF,R1 


1$: 


TSTB 


(RD+ 




BNE 


1$ 




SUB 


#<MSGBUF+1>,R1 




MOV 


Rl, MSGLEN 




.GTLIN 


#CNLBUF,#CNLPRT 




MOV 


//MSGBLK, RO 




EMT 


375 




BCC 


9$ 




MOVB 


@#ERRBYT,R0 




DEC 


RO 




ASL 


RO 




. PRINT 


ERRTBL(RO) 




.EXIT 




9$: 


CLRB 


CNLBUF+6 




. PRINT 


#DONEOK 




.PRINT 


#CNLBUF 




.EXIT 






.NLIST 


BEX 


MSGBLK: 


.BYTE 


0,104 




.WORD 


CNLBUF 




.WORD 


MSGBUF 


MSGLEN: 


.WORD 






;EMT error byte 

Get the message to be queued 
Point to beginning of buffer 
Find end of message 

Determine message length 

accounting for post-increment 

Set message length in EMT arg block 

Get the six character channel name 

Point to EMT arg block to 

Send message on named channel 

Branch if no error 

Which error? 

Zero offset 

Convert to word index 

Display the appropriate message 



;Make channel name ASCIZ 
; Inform user message queued 
;on channel CNLBUF 



;EMT block: send message on named channel 
; Address of channel name 
;Address of message 
;Char length of message 
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ERRTBL: 



BSYERR: 

FULERR: 

OHOH: 

TRNERR: 

MSGPRT : 

CNLPRT: 

DONEOK: 

CNLBUF: 
MSGBUF : 



.WORD 

.WORD 

.WORD 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCII 

.EVEN 

.BLKB 

.BLKB 



BSYERR ; Table of send error messages 

FULERR 

OHOH ;Error code 3 not used 

TRNERR 

/?SNDMSG-F -Maximum number of messages have been queued./ 

/7SNDMSG-F-A11 message channels are busy./ 

/?SNDMSG-F-This is a non-existent error./ 

/?SNDMSG-W-Message was too long, truncated./ 

/Message to be queued: / 

<15><12>/Channel Name (six characters max): /<200> 

/Message queued on channel /<200> 



80. 
80. 



;First 6 chars to contain file name 
; Message buffer. 



,END 



START 



10.3 Checking for pending messages 

The following EMT is used to receive a message from a named channel if a 
message is pending on the channel. If no message is pending, an error code (3) 
is returned, and the program is allowed to continue execution. The form of the 
EMT is: 



EMT 



375 



with R0 pointing to the following argument area: 



.BYTE 
.WORD 
.WORD 
.WORD 



0,105 
chadr 
msadr 
mssiz 



where "chadr" points to a field with a six character channel name, "msadr" 
points to the buffer in which the message is to be placed, and "mssiz" is the 
size of the message buffer (bytes). 

If a message is received, its length (bytes) is placed in R0 on return from the 
EMT. If the message is longer than the message buffer (mssiz), only the first 
part of the message will be received. 



Errors: 



Code Meaning 



No message was queued on the named channel. 

Message was longer than the receiving buffer. 
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Example: 

.TITLE GETMSG 



Demonstrates use of the TSX-Plus EMT to check for pending messages in the 
interprocess message communication facility. 



.MCALL .EXIT, .PRINT, .GTLIN 



ERRBYT = 52 



START: .GTLIN #CNLBUF , //CNLPRT 



2$: 
5$: 



MOV 

EMT 

BCC 

CMPB 

BEQ 

.PRINT 

.EXIT 

.PRINT 

.PRINT 

.PRINT 

.EXIT 



#MSGBLK,R0 

375 

5$ 

@#ERRBYT,#4 

2$ 
#NOMERR 

#TRNERR 
#PNDMSG 
#MSGBUF 



;EMT error byte 

;Get the channel name 

;Put EMT argument block address in RO 

;EMT to check channel for message 

;Error? 

;Only two errors possible 

;Overflow message buffer? 

;No message 

; Print truncation warning 
; Print message preamble 
;Print actual message 



; GETMSG EMT block 
; Channel name buffer address 
;Buffer address to receive message 
; Buffer length 



MSGBLK: .BYTE 0,105 

.WORD CNLBUF 

.WORD MSGBUF 

.WORD 81. 

.NLIST BEX 

CNLBUF: .BLKB 80. ; First 6 chars are channel name 

MSGBUF: .BLKB 80. ;Message buffer 

.WORD ; Insure ASCIZ 

CNLPRT: .ASCII /Channel Name (6 chars): /<200> 

NOMERR: .ASCIZ /?GETMSG-F-No messages pending in named channel./ 

TRNERR: .ASCIZ /?GETMSG-W-Message truncated/<7> 

PNDMSG: .ASCIZ /Message pending in named queue is:/ 

.END START 

10.4 Waiting for a_ message 

The following EMT is used to suspend execution of a program until a message 
becomes available on a named channel. The form of the EMT is: 
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EMT 375 

with RO pointing to the following argument area: 

.BYTE 0,106 

.WORD chadr 

.WORD msadr 

.WORD mssiz 

where "chadr" points to a six byte field containing the channel name, "msadr" 
points to the buffer where the message is to be placed, and "mssiz" is the size 
of the message buffer (bytes). 

The length of the received message (bytes) is placed in RO on return from the 

EMT. 



Errors: 



Code Meaning 



1 
4 

Example : 



All message channels are busy. 

Message was longer than the receiving buffer 



.TITLE WATMSG 
.ENABL LC 



; Demonstrate TSX-Plus EMT to wait for a queued message from the 
; interprocess message communication facility. 

.MCALL .EXIT, .PRINT, .GTLIN 



Tir» r»T>\r r n 


_ CO 




START: 


.GTLIN 


#CNLBUF , #CNLPRT 




.PRINT 


//WAITNG 




MOV 


#MSGBLK,R0 




EMT 


375 




BCC 


5$ 




CMPB 


@#ERRBYT,#1 




BHI 


2$ 




.PRINT 


#N0MERR 




.EXIT 




2$: 


.PRINT 


#TRNERR 


5$: 


.PRINT 


//RCVMSG 



iJJill CJL1W1 UJTLt 



.PRINT //MSGBUF 
.EXIT 



;Get the channel name 

; Explain waiting 

;Put EMT argument block address in RO 

;EMT to check channel for message 

;Check for error 

;Error? 

;Message truncated 

;A11 channels busy 

; Print truncation warning 
; Print message preamble 

; Print actual message 



MSGBLK: .BYTE 0,106 
.WORD CNLBUF 



; WATMSG EMT block 

; Channel name buffer address 
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.WORD 




.WORD 


CNLBUF : 


.BLKB 


MSGBUF : 


.BLKB 




.WORD 




.NLIST 


CNLPRT: 


.ASCII 


WAITNG: 


.ASCII 




.ASCIZ 


NOMERR: 


.ASCIZ 


TRNERR: 


.ASCIZ 


RCVMSG: 


.ASCIZ 



;Buffer address to receive message 

; Buffer length 

; Channel name first 6 chars 

;Message buffer 

; Insure ASCIZ 



MSGBUF 

81. 

80. 

80. 



BEX 

/Channel Name (6 chars): /<200> 

/Waiting for a message . . ./<15><12> 

/Go to another line and send me something./ 

/?WATMSG-F-A11 message channels are busy./ 

/?WATMSG-W-Message truncated. /<7> 

/Message received in named queue is:/ 



,END 



START 
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11. REAL-TIME PROGRAM SUPPORT 

TSX-Plus provides a real-time program support facility that allows multiple 
real-time programs to run concurrently with normal time-sharing operations. 
The basic functions provided by this facility are summarized below. 

1. The ability to map the I/O page into the user's virtual memory region 
so that device status and control registers may be directly accessed 
by the program. 

2. The ability to connect device interrupt vectors to program interrupt 
service routines running at fork level or to program completion 
routines running at user-selectable priority levels with full job 
context. 

3. The ability for a program to lock itself in memory so that rapid 
Interrupt response can be assured ~ 

4. The ability for a program to suspend its execution until an interrupt 
occurs. 

5. The ability to set execution priorities for tasks. 

6. The ability to convert a virtual address within the job's region to a 
physical address for DMA I/O control. 

7. The ability to map a virtual address region to a physical address 
region. 

8. The ability for a program to declare a list of addresses of device 
control registers to be reset when the program exits or aborts 

(.DEVICE EMT) e 

Real-time support features are only available if the real-time support facility 
is included in TSX-Plus when the system is generated. 

A program must have operator privilege to use any of the real-time features 
described in this chapter. The real-time facilities are available to both 
normal jobs controlled by time-sharing lines and to detached jobs. Note that 
detached jobs that are specified during system generation for automatic startup 
run with operator privilege; detached jobs started by time-sharing users have 
operator privilege only if the user starting them does. 

11. 1 Accessing the I/O page 

A basic facility required by most real-time programs is the ability to access 
the PDP-11 I/O page (160000-177777) which contains the device control and 
status registers. Under TSX-Plus, addresses in this range are normally mapped 
to a simulated RMON or may be used as normal program space. This is done since 
many old programs require direct access to certain system values at fixed 
offsets into RMON, although recent programs should access these values with the 
.GVAL and .PVAL EMTs. TSX-Plus provides several EMTs to deal with mapping of 
the I/O page and accessing locations within it. These are discussed below. 
See Chapter 8 for a discussion of various mapping techniques which may be used 
under TSX-Plus. 
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A TSX-Plus real-time program can access the I/O page in one of two ways: It 
can cause the program's virtual address region in the range 160000 to 177777 to 
be mapped directly to the I/O page so that it can directly access device 
registers; or it can leave the virtual address range mapped to the simulated 
RMON and use a set of EMTs to peek, poke, bit-set and bit-clear registers in 
the I/O page. It is much more efficient to directly access the device control 
registers by mapping the I/O page into the program's virtual address region 
than to use EMTs to perform each access. However, this technique will not work 
if the program must also directly access offsets inside RMON. The correct way 
for a program to access RMON offsets is to use the .GVAL EMT which will work 
even if the I/O page is mapped into the program region. 

11.1.1 EMT to map the I/O page into the program space . 



The following EMT can be used to cause the program's virtual address region in 
the range 160000 to 177777 to be mapped to the 1/0 page. 
The form of the EMT is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 5,140 

The I/O page mapping set up by this EMT remains in effect until the program 
exits, chains, or the EMT described in the next section is used to remap to 
RMON. Note that completion routines and interrupt service routines run with 
the same memory mapping as the main-line code of the job. 

The .GVAL EMT with offset value -8. may be used to determine if PAR 7 is 
currently mapped to the I/O page or to the simulated RMON. See the description 
in Chapter 7 of the special use of .GVAL for further information. 

Example: 

.TITLE MAPI0P 
.ENABL LC 

; Demonstrate TSX-Plus EMTs to map to the 1/0 page and back to RMON 

RM0NST = 54 ;SYSC0M location holding base of RMON 

CONFIG = 300 ;Fixed offset into RMON of CONFIG word 

RCSR = 176540 ; Serial line RCSR address 

RBUF = RCSR+2 ;Line input buffer address 

CTRLC = 3 ;Control-C 

.MCALL .PRINT, .EXIT, .TTY0UT, .GVAL 
.GL0BL PRTOCT 

START: CALL SHOMAP ;Display current PAR 7 mapping 
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CALL 



SHODAT 



1$: 



2$; 



3$: 



.PRINT 


#IOPMSG 


MOV 


#MAPIOP,RO 


EMT 


375 


BCC 


1$ 


.PRINT 


#NOPRIV 


.EXIT 




CALL 


SHOMAP 


.PRINT 


//TYPE 


MOV 


@#RCSR,CSRSAV 


CLR 


@#RCSR 


TSTB 


@#RCSR 


BPL 


2$ 


MOVB 


@#RBUF,R0 


CMPB 


RO,#CTRLC 


BEQ 


3$ 


.TTYOUT 




BR 


2$ 


MOV 


CSRSAV,@#RCSR 


.PRINT 


//GOBACK 


MOV 


#MAPMON,R0 


EMT 


375 


CALL 


SHOMAP 


CALL 


SHODAT 


.EXIT 





Demonstrate "RMON" mapping 

Say we are switching to I/O page mapping 

Point to EMT arg block to 

Map to I/O page 

Branch if OK to map 

You aren't allowed to do that 

Display current PAR 7 mapping 

Prompt for input from I/O page 

Save a copy of current CSR 

Disable interrupts on serial line 

Is anything available from the line 

No, keep checking 

Get the new character 

Should we quit? 

Quit on ~C 

Display the character 

And repeat 

Restore original CSR 

Say we are returning to original mapping 

Point to EMT arg block to 

Map back to simulated RMON 

Display current PAR 7 mapping 

And prove we are back 



SHOMAP: .PRINT #MAPMSG 

.GVAL #AREA,#-8. 

ASL RO 

.PRINT CURMAP(RO) 
RETURN 



; Current mapping preface 

;What is our current PAR 7 mapping? 

;Convert to word offset 

;Show which one it is 



SHODAT: 



.PRINT 

MOV 

MOV 

CALL 

RETURN 



#CNFGIS 
@#RMONST,R0 
C0NFIG(R0),R0 
PRTOCT 



; Preface config value 

;Pick up pointer to RMON base 

;Get the current CONFIG value 

; Display it 



MAPIOP: 

MAPMON: 

AREA: 

CSRSAV: 

CURMAP: 



TORMON: 
TOIOPG: 
MAPMSG: 



.BYTE 5,140 

.BYTE 6,140 

.WORD 10 

.WORD 

.WORD TORMON 

.WORD TOIOPG 

.NLIST BEX 

.ASCIZ /simulated RMON./ 

.ASCIZ "I/O page." 

.ASCII /PAR 7 is currently mapped to /<200> 



;EMT arg block to map to I/O page 
;EMT arg block to map to "RMON" 
;EMT arg block 

;Save CSR for restoration on exit 
; Current mapping message table 
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CNFGIS: .ASCII /Current value of CONFIG word in simulated RMON is /<200> 

TYPE: .ASCIZ /Characters entered on serial line will be displayed here:/ 

IOPMSG: .ASCIZ <12>"Now switching PAR 7 mapping to the I/O page." 

GOBACK: .ASCIZ <1 5X1 2>/Re turning PAR 7 mapping to simulated RMON./ 

NOPRIV: .ASCII /Real-time support not specified during TSGEN or / 

.ASCIZ /user not privileged./ 

.END START 



11.1.2 EMT to remap the program region to the simulated RMON. 

The following EMT can be used to cause the virtual address mapping region of 
the job in the range 160000 to 177777 to be returned to normal mapping if it 
had previously been mapped to the I/O page. The form of the EMT is: 



EMT 



375 



with R0 pointing to the following argument area: 

.BYTE 6,140 

Example: 

See the example program MAPIOP in the section on mapping the I/O page into the 
program space. 



11.1.3 EMT to peek at the 1/0 page. 

The following EMT can be used to access a word in the 1/0 page without 
requiring the job's virtual address region to be mapped to the I/O page. (Note 
that the .PEEK and .POKE EMTs can also be used to access parts of the 1/0 page. 
See Chapter 14 for more information on the effects of the .PEEK and .POKE EMTs 
with TSX-Plus.) The form of this EMT is: 



EMT 



375 



with R0 pointing to the following argument area: 



.BYTE 
.WORD 



1,140 
address 



where "address" is the address of the word in the 1/0 page to be accessed. The 
contents of the specified word in the 1/0 page are returned in R0. The 
carry-flag is set on return if real-time support was not included in the 
generation of TSX-Plus or the job does not have operator privilege. Note that 
with this and other EMTs that access the 1/0 page, if an invalid address is 
specified, an error will result with the message: 

?M0N-F -Kernel mode trap within TSX-Plus 
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.TITLE PEEKIO 
.ENABL LC 

demonstrate TSX-Plus EMTs to peek and poke into the I/O page 



= 3 



CTRLC 
RMONST = 54 
CONFIG = 300 
RCSR 
RBUF 



= 176540 
= RCSR+2 



;Control-C 

; Pointer in SYSCOM area to start of "RMON' 

; Fixed offset into "RMON" of config word 

; Serial line RCSR address 

;Line input buffer address 



. MCALL . PR INT , . EXIT , . TTYOUT , . GVAL 
.GLOBL PRTOCT 



START: CALL SHOMAP 
CALL SH0C0N 



1$: 



2$: 



3$: 



MOV 


//PEEKIO, RO 


EMT 


375 


BCC 


1$ 


.PRINT 


//NOPRIV 


.EXIT 




MOV 


R0,CSRSAV 


CLR 


POKVAL 


MOV 


#P0KEI0,R0 


EMT 


375 


.PRINT 


//TYPE 


MOV 


//PEEKIO, RO 


EMT 


375 


TSTB 


RO 


BPL 


2$ 


ADD 


#2 , PEKADD 


MOV 


//PEEKIO, RO 


EMT 


375 


CMPB 


R0, #CTRLC 


BEQ 


3$ 


.TTYOUT 




SUB 


#2 , PEKADD 


BR 


2$ 


MOV 


CSRSAV, POKVAL 


MOV 


#P0KEI0,R0 


EMT 


375 



Display current PAR 7 mapping 
Demonstrate "RMON" mapping 

Point to EMT arg block to 
Peek into the I/O page 
Branch if OK 
You aren't allowed to do that 

Save a copy of current CSR 

Want to disable interrupts 

Point to EMT arg block to 

Poke a value into the I/O page 

Shouldn't be error if peek worked 

Prompt for input from I/O page 

Point to EMT arg block to 

Check the RCSR 

Is anything available from the line 

No, keep checking 

Point to the receiver buffer 
Point to EMT arg block to 
Get the input character 
Should we quit? 
Quit on ~C 

Display the character 
Point back to the RCSR 
And repeat 

;Want to restore the original CSR status 
; Point to EMT arg block to 
;Restore the CSR 



.EXIT 
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SHOMAP: .PRINT 
.GVAL 
ASL 
.PRINT 
RETURN 

SHOCON: .PRINT 
MOV 
MOV 
CALL 
RETURN 



#MAPMSG 
#AREA,#-8. 
RO 
CURMAP(RO) 



//CNFGIS 
@#RMONST,RO 
CONFIG(R0),R0 
PRTOCT 



;Current mapping preface 

;What is our current PAR 7 mapping? 

;Convert to word offset 

;Show which one it is 



;Preface config value 

;Pick up pointer to RMON base 

;Get the current CONFIG value 

;Display it 



;EMT arg block to peek into the I/O page 

; Address to be read 

;EMT arg block to poke into the I/O page 

;Address to be modified 

;Word to be moved to POKADD 

;EMT arg block 

;Save CSR for restoration on exit 

; Current mapping message table 



PEEKIO: .BYTE 1,140 

PEKADD: .WORD RCSR 

POKEIO: .BYTE 2,140 

POKADD: .WORD RCSR 

POKVAL: .WORD 

AREA: .WORD 10 

CSRSAV: .WORD 

CURMAP: .WORD T0RM0N 

.WORD TOIOPG 

.NLIST BEX 

TORMON: .ASCIZ /simulated RMON./ 

TOIOPG: .ASCIZ "I/O page." 

MAPMSG: .ASCII /PAR 7 is currently mapped to /<200> 

CNFGIS: .ASCII /Current value of CONFIG word in simulated RMON is /<200> 

TYPE: .ASCIZ /Characters entered on serial line will be displayed here:/ 

NOPRIV: .ASCII /Real-time support not specified during TSGEN or / 

.ASCIZ /user not privileged./ 

.END START 



11.1.4 EMT to poke into the I/O page. 

The following EMT can be used to store a value into a cell in the I/O page 
without requiring the job's virtual address region to be mapped to the I/O 
page. The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument area: 



.BYTE 
.WORD 
.WORD 



2,140 

address 

value 



where "address" is the address of the cell in the I/O page and "value" is the 
value to be stored. The carry-flag is set on return if real-time support was 
not included in the TSX-Plus generation or the job does not have operator 
privilege. 
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Example ; 
See the example program PEEKIO in the section on peeking into the I/O page. 



11.1.5 EMT to bit-set a. value into the I/O page. 

The following EMT can be used to perform a bit-set (BIS) operation into a cell 
in the I/O page without requiring the job's virtual address region to be mapped 
to the I/O page. The form of the EMT is: 



EMT 



375 



with RU pointing to the following argument area: 



.BYTE 
.WORD 
.WORD 



3,140 

address 

value 



where "address" is the address of the cell in the I/O page and "value" is the 
value that will be bit-set into the cell. An error will cause the carry-flag 
to be set on return, indicating that either real-time support was not included 
in the TSX-Plus generation or the job does not have operator privilege. 

Example: 



rpTrnT 



TlTflTA 



.ENABL LC 
demonstrate TSX-Plus EMTs to bit-set and bit-clear into the I/O page 



CTRLC = 3 
RMONST = 54 

TATTMTIT — 1 OH 
J.i.1 J. mDij — j. v/v 

CONFIG = 300 
RCSR = 176540 
RBUF = RCSR+2 



;Control-C 

; Pointer in SYSCOM area to start of "RMON* 

;Fixed offset into "RMON" of config word 
; Serial line RCSR address 
;Line input buffer address 



.MCALL .PRINT, .EXIT, .TTYOUT, .GVAL 



START: CALL 
CALL 



SHOMAP 
SHOCON 



1$: 



MOV #BICI0,R0 

EMT 375 

BCC 1$ 

.PRINT #N0PRIV 
.EXIT 

. PRINT #TYPE 



;Display current PAR 7 mapping 
demonstrate "RMON" mapping 

;Want to clear input interrupts 
; Point to EMT arg block to 
;Clear a bit in the I/O page 
; Branch if OK 
;You aren't allowed to do that 

;0K, interrupts should be disabled 
; Prompt for input from I/O page 
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2$: 


MOV 


#PEEKIO,RO 




EMT 


375 




TSTB 


RO 




BPL 


2$ 




ADD 


#2,PEKADD 




MOV 


#PEEKIO,R0 




EMT 


375 




CMPB 


R0,#CTRLC 




BEQ 


3$ 




.TTYOUT 






SUB 


#2,PEKADD 




BR 


2$ 


3$: 








MOV 


#BISIO,RO 




EMT 


375 



; Point to EMT arg block to 

; Check the RCSR 

;Is anything available from the line 

;No, keep checking 

; Point to the receiver buffer 

; Point to EMT arg block to 

;Get the input character 

; Value from peek is returned in RO 

; Should we quit? 

;Quit on ~C 

; Display the character 

; Point back to the RCSR 

;And repeat 

;Want to set input interrupts 
; Point to EMT arg block to 
;Set a bit in the I/O page 



.EXIT 



SHOMAP: 


.PRINT 


#MAPMSG 




.GVAL 


#AREA,#-8. 




ASL 


RO 




.PRINT 


CURMAP(RO) 




RETURN 




SHOCON: 


.PRINT 


#CNFGIS 




MOV 


@#RMONST,R0 




MOV 


CONFIG(RO) ,R0 




CALL 


PRTOCT 




RETURN 




PRTOCT: 


MOV 


R1,-(SP) 




MOV 


R2,-(SP) 




MOV 


R3,-(SP) 




MOV 


#EOW,R2 




MOV 


#6,R3 


1$: 


MOV 


R0,R1 




BIC 


#177770, Rl 




ADD 


#'0,R1 




MOVB 


R1,-(R2) 




CLC 






ROR 


RO 




ASH 


#-2,R0 




SOB 


R3,l$ 




.PRINT 


#CHARS 




MOV 


(SP)+,R3 




MOV 


(SP)+,R2 




MOV 


(SP)+,R1 



; Current mapping preface 

;What is our current PAR 7 mapping? 

; Convert to word offset 

;Show which one it Is 



; Preface config value 

;Pick up pointer to RMON base 

;Get the current CONFIG value 

;Display it 



;Save rl-r3 on the stack 

;R0 contains word of interest 

; Point to end of 6 char output buffer 

;Set up counter for 6 chars 

;Set up mask for low 3 bits (Is digit) 

;Get low 3 bits 

;Convert to ascii 

;Fill octal digits in from end 



; Shift out bits just converted 
; Repeat for 6 chars 
;Display result at console 
;Restore registers rl-r3 
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RETURN 


PEEKIO: 


.BYTE 


PEKADD: 


.WORD 


BICIO: 


.BYTE 




.WORD 




.WORD 


BISIO: 


.BYTE 




.WORD 




.WORD 


AREA: 


.BLKW 


CSRSAV: 


.WORD 


CHARS: 


.BLKB 


EOW: 


.WORD 


CURMAP: 


.WORD 




.WORD 




.NLIST 


TORMON: 


.ASCIZ 


TOIOPG: 


.ASCIZ 


MAPMSG: 


.ASCII 


CNFGIS: 


.ASCII 


TYPE: 


.ASCIZ 


NOPRIV: 


.ASCII 




.ASCIZ 




.END 



1,140 

RCSR 

4,140 

RCSR 

INTNBL 

3,140 

RCSR 

INTNBL 

10 



6 



TORMON 

TOIOPG 

BEX 

/simulated RMON./ 

"I/O page." 

/PAR 7 is currently mapped to /<200> 

/Current value of CONFIG word in simulated RMON is /<200> 

/Characters entered on serial line will be displayed here:/ 

/Real-time support not specified during TSGEN or / 

/user not privileged./ 

START 



EMT arg block to peek into the I/O page 

Address to be read 

EMT arg block to clear a bit in the I/O page 

Input status register 

Interrupt enable mask 

EMT arg block to set a bit in the I/O page 

Input status register 

Interrupt enable mask 

EMT arg block 

Save CSR for restoration on exit 

6 char output buffer 

Terminator for .PRINT 

Current mapping message table 



11.1.6 EMT to do a bit-clear into the I/O page. 

The following EMT can be used to perform a bit-clear (BIC) operation into a 
cell in the I/O page without requiring the job's virtual address region to be 
mapped to the I/O page. The form of the EMT is: 



^7^ 



with R0 pointing to the following argument area: 



.BYTE 
.WORD 
.WORD 



4,140 

address 

value 



where "address" is the address of the cell in the I/O page and "value" is the 
value to be bit-cleared into the specified cell. An error will cause the 
carry-flag to be set on return, indicating that either real-time support was 
not included in the TSX-Plus generation or the job does not have operator 
privilege. 

Example: 

See the example program BISIO in the section on doing a bit-set into the I/O 
page. 
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11.2 Mapping to a. physical memory region 

In certain circumstances, it is desirable to map a portion of virtual memory to 
a specific area in physical memory which is not in the I/O page. Possible 
examples would be ROM memory or an array processor. This mapping is done by 
altering one or more of the Page Address Registers (PARs) for the job. Each 
PAR maps 8192 bytes of memory from the virtual job space into physical memory. 
There are 8 PAR's (8*8192=64Kb) . The region of memory mapped through each PAR 
is shown by the table below: 

PAR Virtual Region 



000000 - 017777 

1 020000 - 037777 

2 040000 - 057777 

3 060000 - 077777 

4 100000 - 117777 

5 120000 - 137777 

6 140000 - 157777 

7 160000 - 177777 



The form of this EMT is: 

EMT 375 

with R0 pointing to the following argument area: 

.BYTE 17,140 

.WORD par-number 

.WORD phys-address 

.WORD size 

.WORD access 

"par-number" is the number of the Page Address Register (PAR) that 
corresponds to the beginning of the program virtual address region that is 
to be mapped. 

"phys-address" Is the physical address to which the virtual address is to 
be mapped. The physical address is specified as an address divided by 64 
(decimal). That is, the physical address represents the 64-byte block 
number of the start of the physical region. Note that the physical 
address of any 64-byte block within a 22-bit physical address space can be 
represented in 16 bits. 

"size" is the number of 64-byte blocks of memory to be mapped through the 
virtual region. Each PAR can map up to 128 64-byte blocks of memory. If 
more than 128 blocks are mapped, successively higher PARs are set up to 
map the remainder of the region. 
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"access" indicates if the mapped region is to be allowed read-only access 
or both read and write access: = read-only; 1 = read/write. 

This EMT may be used to map any of the PARs to any physical address regions 
desired (even to map PAR 7 to the I/O page). The use of this EMT does not 
affect mapping set up previously for other PARs. If the "size" parameter is 
(zero), all PAR mapping is reset and the normal virtual address mapping for the 
job is restored. 

An error on return indicates either that real-time support was not included in 
the TSX-Plus generation process or that the job does not have operator 
privilege. 

Note that this EMT is not equivalent to the extended memory EMTs used with PLAS 
(Program's Logical Address Space) requests and virtual overlays and virtual 
arrays. See Chapter 8 for a discussion of job environment and the appropriate 
RT-11 manuals for a more complete discussion of PLAS features. 

Example: 

.TITLE MAPPHY 
•ENABL LC 

; Demonstrate TSX-Plus EMT to map to any physical address 



INTNBL = 100 
RCSR = 176540 
RBUF = RCSR+2 



;L.ontroi-u 

; Interrupt enable bit 

; Serial line RCSR address 

;Line input buffer address 



.MCALL .PRINT, .EXIT, .TTYOUT, .GVAL 



START: .PRINT #MAPMS( 





MOV 


//MAPPHY, R0 




EMT 


375 




BCC 


1$ 




.PRINT 


#N0PRIV 




.EXIT 




1$: 


.PRINT 


#TYPE 




BIC 


//INTNBL, @#RCSR 


2$: 


TSTB 


@#RCSR 




BPL 


2$ 




MOVB 


@#RBUF,R0 




CMPB 


R0,#CTRLC 




BEQ 


3$ 




T"r»vnT TTTi 

• JL x j. \J w J. 






BR 


2$ 


3$: 


CLR 


SIZE 




MOV 


//MAPPHY, R0 



;Say we are switching to physical mapping 

; Point to EMT arg block to 

;Map to physical memory 

; Branch if OK to map 

;You aren't allowed to do that 

Prompt for input from I/O page 

Disable interrupts on serial line 

Is anything available from the line 

No, keep checking 

Get the new character 

Should we quit? 

Quit on ~C 

Display the character 

And repeat 

If .size is 0, original mapping is restored 
Point to EMT arg block to 
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EMT 375 
.EXIT 



MAP PHY: .BYTE 
.WORD 
.WORD 
SIZE: .WORD 
.WORD 
.NLIST 
MAPMSG: .ASCIZ 
TYPE: .ASCIZ 
NOPRIV: .ASCII 
.ASCIZ 
.END 



;Revoke mapping to physical address 



;EMT arg block to map to physical memory 
; remap PAR 7 

; 17760000/64. address to map into PAR 7 
;size of region to be mapped - full 8kb 

jaccess 0=read-only, l=read/write 



17,140 

7 

177600 

20000 

1 

BEX 

/PAR 7 mapping is now directed to top of physical memory./ 

/Characters entered on serial line will be displayed here:/ 

/Real-time support not specified during TSGEN or / 

/user not privileged./ 

START 



11.3 Requesting exclusive system control 

The following EMT allows real-time jobs to gain exclusive access to the system 
while they perform time-critical tasks. The form of the EMT is: 



EMT 



375 



with R0 pointing to the following argument block: 

.BYTE 14,140 

The effect of this EMT is to cause the TSX-Plus job scheduler to ignore all 
other jobs, even higher priority jobs - including fixed-high-priority jobs, 
until the real-time job relinquishes exclusive access control. Note that this 
is different (and more powerful) than giving the real-time job a higher 
execution priority because all other jobs are completely prevented from 
executing even if the real-time job goes into a wait state causing the CPU to 
become idle. 

The form of the EMT used to relinquish exclusive system access is: 

EMT 375 
with R0 pointing to the following argument block: 

.BYTE 15,140 

In order to use either of these EMTs, the real-time option must be included 
when the TSX-Plus system is generated and the executing job must have operator 
command privilege. 

The following restrictions apply to a job that has issued an exclusive access 

EMT: 
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1. The job is automatically locked in memory during the time it has 
exclusive access to the system. If you wish to use the TSX-Plus EMT 
that locks a job in the lowest portion of memory, that EMT must be 
executed before calling this EMT to gain exclusive access to the 
system. ^ 

2. The size of the job may not be changed while it has exclusive access 
to the system. 

Exclusive access is automatically relinquished if the job exits or traps but is 
retained if the job chains to another job. 

Example : 

.TITLE STEALS 
.ENABL LC 

; Demonstrate TSX-Plus EMT to obtain exclusive system control 



LEAD IN 


~ 


35 


JSW 


= 


44 


TTSPC 


= 


10000 


NOWAIT 


= 


100 



;TSX-Plus program controlled terminal 
;option lead-in character. 
;Job status word address 
;TT special mode bit in JSW 
;TT nowait bit in JSW 



.MCALL .PRINT, .TTY0UT, .TTYIN, .EXIT 

START: MOV #TTSPC! NOWAIT, @#JSW ;Set TT special mode and nowait 

;bits in the JSW 
.TTY0UT #LEADIN ;And make TSX-Plus understand both 
.TTY0UT #'S 
.TTYOUT #LEADIN 
.TTY0UT #'U 





.PRINT 


#MSG 




MOV 


#STEALS,R0 




EMT 


375 


» • • • 


.TTYIN 






MOV 


#LETGO,R0 




EMT 


375 




.EXIT 






.NLIST 


BEX 


STEALS: 


.BYTE 


14, 140 


LETG0: 


• BYTE 


15,140 


MSG: 


.ASCII 


/Other use 



.END 



; Prompt for input 

; Point to EMT arg block to 

; Steal exclusive system control 

;Time critical processing goes here 

; Simulated here with terminal input 

; Point to EMT arg block to 

;Relinquish exclusive system control 



;EMT arg block for exclusive system control 
;EMT arg block to relinquish exclusive control 
/Other users are locked out until you press a key:/<200> 

START 
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11.4 Locking a job in memory 

In time-critical real-time applications where a program must respond to an 
interrupt with minimum delay, it may be necessary for the job to lock itself in 
memory to avoid program swapping. This facility should be used with caution 
since if a number of large programs are locked in memory there may not be 
enough space left to run other programs. 

TSX-Plus provides two program locking facilities. The first moves the program 
to the low end of memory before locking it; this is done to avoid fragmenting 
available free memory. This type of lock should be done if the program is 
going to remain locked in memory for a long period of time. However, this form 
of locking is relatively slow since it may involve program swapping. The 
second locking facility simply locks the program into the memory space it is 
occupying when the EMT is executed without doing any repositioning. This EMT 
has the advantage that it is extremely fast but free memory space may be 
non-contiguous . 

The form of the EMT used to lock a program in low memory (re-positioning if 
necessary) is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 7,140 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX-Plus generation or the job does 
not have operator privilege. 

The form of the EMT used to lock a job in memory without repositioning it is: 

EMT 375 
with RO pointing to the following argument area: 

.BYTE 13,140 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX-Plus generation or the job does 
not have operator privilege. 

Example : 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 
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11.5 Unlocking £ job from memory 

When a job locks itself in memory, it remains locked until the job exits or the 
following EMT is executed. The form of the EMT used to unlock a job from 
memory is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 10,140 

An error will cause the carry=flag to be set on return, indicating that either 
real-time support was not included in the TSX-Plus generation or the job does 
not have operator privilege. 

Example : 

See the 

interrupt to a completion routine. 



see tne exaiupj.e px.ugi.ciui ah»ij^ xu mc oc^-tion Oii connecting a real— t. 



11.6 Sus pend ing /Re suming program execution 

The RT-11 standard .SPND and .RSUM EMTs are used by TSX-Plus real-time jobs to 
suspend and resume their execution- Frequently, a real— time job will begin its 
execution by connecting interrupts to completion routines and doing other 
initialization and then will suspend its execution while waiting for a device 
interrupt to occur. 

The .SPND EMT causes the main-line code in the job to be suspended. Completion 
routines are not affected and execute when interrupts occur. If a completion 
routine executes a .RSUM EMT, the main-line code will continue execution at the 
point following the .SPND when the completion routine exits. Refer to the 
RT-11 Programmer's Reference Manual for further information about the use of 
.SPND and .RSUM. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 
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11. 7 Converting a virtual address to a_ physical address 

When controlling devices that do direct memory access (DMA), it is necessary to 
be able to obtain the physical memory address (22-bit) that corresponds to a 
virtual address in the job. Note that a job should lock itself in memory 
before performing this EMT. The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument area: 

.BYTE 0,140 

.WORD virtual-address 

.WORD result-buffer 

where "virtual-address" is the virtual address that is to be converted to a 
physical address and "result-buffer" is the address of a two word area that is 
to receive the physical address. The low-order 16 bits of the physical address 
are stored in the first word of the result buffer and the high-order 6 bits of 
the physical address are stored in bit positions 4-9 of the second word of the 
result buffer. 

An error will cause the carry-flag to be set on return, indicating that either 
real-time support was not included in the TSX-Plus generation or the job does 
not have operator privilege. 



Example : 



.TITLE PHYADD 
.ENABL LC 



Demonstrate TSX-Plus EMT to convert a virtual to a physical address 

.MCALL .PRINT,. EXIT 



START: 


MOV 


#L0KJ0B,R0 




EMT 


375 




BCC 


1$ 




.PRINT 


#N0PRIV 




BR 


2$ 


1$: 


. PRINT 


#STRADD 




MOV 


//START, RO 




CALL 


PRTADD 


2$: 


.EXIT 




PRTADD: 


MOV 


R0,VIRADD 




MOV 


#PHYADD,R0 




EMT 


375 




MOV 


BUFFER, Rl 




MOV 


<BUFFER+2>,R2 



; Point to EMT arg block to 

;Lock job in memory 

;Continue if OK 

; Explain the problem 

;and quit 

;Say where this program was loaded 

;Get the virtual address 

;and display it to the terminal 



;Put the virtual address into the arg block 

; Point to EMT arg block to 

;Convert virtual to physical address 

;Retrieve the low address 

;And the high address 
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1$: 



2$: 



3$: 



BIC 

MOV 

ASR 

SOB 

MOV 

MOV 

MOV 

BIC 

ADD 

MOVB 

MOV 

ASR 

ROR 

SOB 

SOB 

. PRINT 

RETURN 



#~C1760,R2 

#4,R3 

R2 

R3,l$ 

#CHREND,R4 

#8.,R3 

R1,R0 

#~C7,R0 

#'0,R0 

R0,-(R4) 

#3,R5 

R2 

Rl 

R5,3$ 

R3,2$ 

R4 



;Use only bits 4-9 
I Throw away bits 0—3 



;Point to end of character output buffer 

;Need to convert 8 digits 

;Get a copy of low bits into RO 

;Mask out all but low digit 

; Convert to ASCII 

;Put low digit in output buffer 

; Shift over 3 bits to next digit 

;Low bit of high address 

;into high bit of low address 

;Do all 8 digits 

; Print out the result 



LuKJOB : 
PHYADD: 
VIRADD: 

BUFFER: 

CHREND: 

NOPRIV: 

STRADD: 



. BYTE 
.BYTE 
.WORD 
.WORD 
.WORD 
.BLKB 
.WORD 

\TT TOT 

.ASCII 
.ASCIZ 
.ASCII 
.END 



1.3,140 

0,140 



BUFFER 

0,0 

10. 





;EMT arg block to lock job in memory 

;EMT arg block to determine physical address 

;Virtual address to be located 

;Location of 2 word result buffer 

;Will hold low and high physical address 

; Buffer to hold ASCII value of address 

;End of ASCII buffer 



/Real-time not included in TSGEN or user / 

/not privileged./ 

/This program is loaded at START = /<200> 

START 



11.8 Specifying a program-abort device reset list 

The standard RT-11 .DEVICE EMT is used by TSX-Plus real-time jobs to specify a 
list of device control registers to be loaded with specified values when the 
job terminates. This feature is useful in allowing real-time devices to be 
turned-off if the real-time control program aborts. The TSX-Plus .DEVICE EMT 
has the same form and options as the standard RT-11 .DEVICE EMT. See the RT-11 
Programmer's Reference Manual for further information. 

The connection between interrupt vectors and interrupt service routines or 
interrupt completion routines is automatically dropped when a job terminates. 
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11.9 Setting processor priority level 

The following EMT allows a program to set the processor priority level. This 
can be useful in a situation where it is necessary for a real-time job to block 
interrupts for a short period of time while it is performing some critical 
operation. On return from this EMT, the job is executing in user mode with the 
specified processor priority level. The form of the EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

.BYTE 16,140 
.WORD prio-level 

where "prio-level" should be 7 to cause interrupts to be disabled or to 
reenable interrupts. Interrupts should not be disabled for a long period of 
time or clock interrupts and terminal I/O interrupts will be lost. 

Note that it is not possible to raise the processor priority level by storing 
directly into the processor status word from a real-time program because the 
PDP-11 hardware disallows modification of the PSW by a user mode program even 
if the program has access to the I/O page. 

Example : 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 

11.10 Setting Job Execution Priority 

Jobs may be assigned priority values in the range to 127 to control their 
execution scheduling relative to other jobs. The priority values are arranged 
in three groups: the fixed-low-priority group consists of priority values from 
up to the value specified by the PRILOW sysgen parameter; the fixed-high- 
priority group ranges from the value specified for the PRIHI sysgen parameter 
up to 127; the middle priority group ranges from (PRIL0W+1) to (PRIHI-1). The 
current values for PRIHI and PRILOW may be determined with the SHOW PRIORITY 
command, or from within a program with a .GVAL request. The following diagram 
illustrates the priority groups: 
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127 



— > 



PRIHI — > 



PRIDEF — > 



PRILOW — > 



— > 



Fixed 
high 
priorities 



Normal 

job 

priorities 



Fixed 
low 
priorities 



Job scheduling is performed differently for jobs in the fixed-high-priority and 
fixed-low-priority groups than for jobs with normal interactive priorities. 
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the 
fixed-high-priority group (PRIHI to 127) execute at fixed priority values. 
That is, the priority absolutely controls the scheduling of the job for 
execution relative to other Tobs. A "iob with a fixed i~>riorit v is allowed to 
execute as long as it wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The 
fixed-low-priority group is intended for use by very low priority background 
tasks. Normal time-sharing jobs should not be assigned priorities in either of 
the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be 
used by normal, interactive, time-sharing jobs. Jobs with these assigned 
priorities are scheduled in a more sophisticated manner than the fixed-priority 
jobs. In addition to the assigned priority, external events such as terminal 
input completion, I/O completion, and timer quantum expiration play a role in 
determining the effective scheduling priority. 

When a job with a normal priority switches to a virtual line, the priority of 
the disconnected job is reduced by the amount specified by the PRIVIR sysgen 
parameter. This causes jobs that are not connected to terminals to execute at 
a lower priority than jobs that are. This priority reduction does not apply to 
jobs with priorities in the fixed-high-priority group or the fixed-low-priority 
group. The priority reduction is also constrained so that the priority or jobs 
in the normal job priority range will never be reduced below the value of 
(PRILOW+1). 
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The following EMT can be used to set the job priority from within a program. 
Unlike the other real-time EMT's in this chapter, this EMT does not require 
operator privilege. The maximum priority which may be used by a job is set by 
the system manager. The job priority can also be set from the keyboard with 
the SET PRIORITY command. The current job priority, maximum allowed priority, 
and fixed-high- and fixed-low-priority boundaries may be determined with the 
.GVAL request. See the TSX-Plus System Manager's Guide for more information on 
the significance of priority in job scheduling. The form of this EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

.BYTE 0,150 
.WORD value 

where "value" is the priority value for the job. The valid range of priorities 
is to 127 (decimal). The maximum job priority may be restricted through the 
logon mechanism. If a job attempts to set its priority above its maximum 
allowed priority, its priority will be set to the maximum allowed. This EMT 
does not return any errors. 

Example : 

See Chapter 7 for an example of the use of this EMT. 

11.11 Connecting interrupts to real-time jobs 

One of the most important uses for real-time jobs is to service interrupts for 
non-standard devices. TSX-Plus provides three mechanisms for connecting 
user-written real-time programs to interrupts: device handlers, interrupt 
service routines, and interrupt completion routines. Interrupt service 
routines and interrupt completion routines permit jobs to process interrupts 
without the necessity of writing a special device handler. However, there are 
restrictions on the use of these two methods which must be considered when 
deciding the appropriate method for handling special device interrupts. 

The fastest method of handling interrupts is to write a device handler 
(driver). Device handlers execute in kernel mode and provide the fastest 
possible response to interrupts. A device handler is the best choice when 
interrupts occur at a rate which significantly loads the system. Device 
handlers written for use with TSX-Plus should conform to the rules for writing 
device handlers for RT-11XM. 

The second method for processing real-time interrupts is to connect the 
interrupt to a real-time interrupt service routine. The interrupt service 
routine is written as a subroutine in a real-time job; it is not necessary to 
write a separate device handler. Interrupt service routines are connected with 
minimal system overhead and can service interrupts quite rapidly (approximately 
2000 per second on an 11/44). Interrupt service routines are called in user 
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mode but can only execute a limited set of system service calls (EMT's). 
Interrupt service routines can trigger the execution of interrupt completion 
routines to perform additional processing. 

The third method for processing real-time interrupts is to connect the 
interrupt to an interrupt completion routine. Real-time interrupt completion 
routines have access to the full job context and can use most system service 
calls (EMT's), but have more overhead and should not be used for interrupts 
that occur more frequently than 200 times per second. 

The following diagram illustrates the different levels of interrupt processing. 
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This diagram shows that there are three "levels" of interrupt processing. 
Level 1 is entered when a hardware interrupt occurs. In this level the 
processor (hardware) priority is set to 7 which causes other interrupt requests 
to be temporarily blocked. After some brief interrupt entry processing, the 
system performs a .FORK operation which queues a request for processing at fork 
level and then drops the processor priority to 0. At this time another 
hardware interrupt can occur, in which case the cycle will be repeated and 
another request for fork level processing will be placed on the queue. Note 
that if .FORK requests are issued at a sustained high rate, such that numerous 
prior requests cannot be serviced, a system error may eventually occur. 

Level 2 processing is also known as "fork level" processing. This level of 
interrupt processing services requests that were placed on a queue by the .FORK 
operation. Hardware interrupts are enabled during this processing and if any 
other interrupts occur their .FORK requests are placed at the end of the queue. 
Interrupt service requests are processed serially in the order that the 
interrupts occurred. Only two system service calls may be used from service 
routines running at fork level: a request to queue a user completion routine 
for subsequent processing; and the .RSUM EMT. 

Level 3 processing occurs in "job state". That is, the TSX-Plus job execution 
scheduler selects the highest priority job or completion routine and passes 
execution to it. Completion routines run with full job context and may issue 
system service calls (except USR calls) as needed. Completion routines are 
serialized for each job. That is, all other completion routines (including 
hisher priority interrupt completion routines) which are scheduled for the same 
job are queued for execution and will not be entered until the current 
completion routine exits. During level 3 processing, interrupts are enabled 
and job execution may be interrupted to process fork level interrupt service 
routines or by higher priority completion routines for other jobs. 

11.11.1 Interrupt service routines . 

Interrupt service routines execute in user mode but require a minimal amount of 
system overhead. When an interrupt is received through a vector which has been 
connected to an interrupt service routine, TSX-Plus executes a .INTEN and a 
.FORK, sets up memory management for the appropriate job, saves the status of 
the floating point unit (FPU) if it is in use, and passes control to the 
interrupt service routine. Using this approach, interrupts may be serviced at 
about 2000 per second on a PDP-11/44. Lower rates should be expected on slower 
processors. 

Several restrictions apply to this method of interrupt processing: 

a) The job must be locked in memory before connecting to the interrupt 
vector and must remain locked in memory as long as the interrupt 

connection is in effect. 

b) The processing done by the interrupt service routine should be brief 
since other interrupts that do .FORKs will be queued until the 
interrupt service routine exits. 
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c) Only two system service calls (EMTs) are valid within a interrupt 
service routine: 

1) A .RSUM EMT may be issued to cause the job's main-line code to 
continue processing if it has done a .SPND. 

2) The TSX-Plus EMT which schedules execution of a completion 
routine. 

Access to the I/O page is possible if the main-line code sets up such mapping 
prior to the interrupt. Registers are undefined on entry to an interrupt 
service routine, and do not have to be preserved by the interrupt service 
routine. 

An interrupt service routine must exit with a RETURN instruction (RTS PC), not 
an RTI . Since interrupt service routines execute at fork level, job scheduling 
is not relevant for them. All fork level processing, whether queued for system 
processing or for an interrupt service routine, is executed in the order in 
which the interrupts were received and execute before any completion routines, 
fixed-priority jobs or normal interactive time-sharing jobs. 

The form of the request to connect an interrupt service routine to a vector is: 

EMT 375 

with RO pointing to the following argument block: 



.BYTE 


20,140 


.WORD 


vector-address 


.WORD 


service-routine 


.WORD 






where "vector-address" is the address of the interrupt vector to which the 
service routine is to be connected, and "service-routine" is the address of the 
entry point of the interrupt service routine. 

The total number of vectors that can be connected either to interrupt service 
routines or interrupt completion routines is determined by the RTVECT parameter 
during TSX-Plus system generation. 



Error: 



Code Meaning 



Real time not included or job not privileged 

1 There are no free interrupt control blocks 

2 Some other job is already connected to that vector 

3 Job is not locked in memory 

The association between an interrupt service routine and an interrupt vector 
may be released by the same EMT as used to disconnect an interrupt completion 
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routine. See the section on releasing an interrupt connection later in this 



Example : 



.TITLE INTSVC 
.ENABL LC 



Demonstrate EMT to implement an interrupt service routine 
Simple file capture program. Steal a time-sharing line 
and put everything that comes in on it into a file. 

.MCALL .TTYIN, .TTYOUT, .EXIT, .PEEK, .POKE, .GVAL, .SCCA 
.MCALL .ENTER, .LOOKUP, .CSISPC , .WRITE, .PURGE, .CLOSE, .DEVICE 



VECTOR 

RCSR 

RBUF 

BUFSIZ 

INTNBL 

CTRLC 

CTRLD 



= 330 
= 176530 
= RCSR+2 
= 256. 
= 100 
= 3 
= 4 



Serial line vector 
Serial line RCSR address 
Serial input buffer address 
Size of buffer in words 
Interrupt enable bit in RCSR 
ASCII control-C 
ASCII control-D 



START: .GVAL 
TST 

MOV 
EMT 
MOV 

EMT 



GETFIL: MOV 



i 6 . 



//AREA, #-6. ;See if job is privileged 

R0 ;1 if priv, if not 

^uii ,j.Meuiiin; exit 11 not priv 

//L0KJ0B,R0 ; Point to EMT arg block to 

375 ;Lock job in memory 

#MAPI0,R0 ; Point to EMT arg block to 

375 ;Map PAR7 into the I/O page 

SP,SPSAVE ;Save SP prior to CSI call 



.CSISPC #0UTSPC,#DEFEXT,#0 ;Get file specification 

BCS 1$ ; Repeat until valid command line 

MOV SPSAVE,SP ;Restore SP, no valid switches 

.ENTER #AREA,//0,//INSPC,//-l ;Open largest possible output file 

BCS 1$ ;0n error, ask for new file 

MOV //BUFFI, BUFPTR ; Initialize buffer pointer 

CLR BLOCK ; Initialize output file block count 

Set up to accept terminal commands 

ctrl-c, ctrl-c to abort; ctrl-d to end transmission 
.SCCA //AREA, //TTSTAT ; Disable control-c abort 
MOV #ACTCTD,R0 ;Point to EMT arg block to 
EMT 375 ; Activate input on "D 

Since we are going to borrow a current time-sharing line, we need 

to save its vector pointers for later restoration 

MOV @#RCSR,CSRSAV ;Save old status bits, esp. int. enable 
.DEVICE #AREA,//DEVLST ; Force restoration of RCSR on exit 
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BIC //INTNBL,@#RCSR 

. PEEK //AREA , //VECTOR 

MOV R0,VECSAV 

. PEEK //AREA , //VECTOR+2 

MOV R0,VECSV2 



Disable interrupts until ready 

Get normal vector pointer 

And save it for later restoration 

Get normal priority 

And save it for later restoration 



; Now attach interrupt service routine to input vector 

MOV //INTSVC,R0 ;Point to EMT arg block to 

EMT 375 ; Schedule interrupt service routine 

GO: BIS #INTNBL,@//RCSR ;Enable interrupts and wait for input 

.TTYIN INBUF ;Wait for terminal command during transfer 



; Resume here when transfer is 

WHOA: BIC #INTNBL,@#RCSR 

CMPB INBUF , //CTRLC 

BNE 5$ 

. PURGE #0 

TST TTSTAT 

BEQ GETFIL 

BR QUIT 

5 $ : CMPB INBUF , //C TRLD 

BNE GO 

CALL FINISH 

. CLOSE #0 



complete, or want to abort 

Disable interrupts (data lost if mistake) 
;Was it a control-c? 
Branch if not 

If CTRL-C, throw away input 
Did we get double control-c's? 
If not, get another file name 
If double control-c, then abort 
Is the transmission done? 
Branch if not 

Write out remainder of current buffer 
If done, close out file 



; Done or abort, restore time-sharing line conditions 
QUIT: MOV #RELVEC,R0 ; Point to EMT arg block to 

EMT 375 ;Release interrupt connection 

.POKE //AREA, //VECTOR+2, VECSV2 ; Restore old priority 
.POKE //AREA, //VECTOR, VECSAV ;And old vector pointer 
.EXIT ;And done! 

; Interrupt service routine, executes at .FORK level 



ISR: 



1$: 



2$: 



MOVB 


@//RBUF,@ BUFPTR 


INC 


BUFPTR 


CMP 


BUFPTR,//BUFF2 


BHI 


1$ 


BLO 


9$ 


MOV 


#BUFF1,WRTPTR 


BR 


2$ 


CMP 


BUFPTR, //BUFEND 


BLO 


9$ 


MOV 


//BUFFI, BUFPTR 


MOV 


#BUFF2,WRTPTR 


MOV 


#SCHWRT,R0 


EMT 


375 



Put char in buffer 

And point to next location 

Which buffer in use? 

Branch if already in second 

Return if first not full 

Exact end of buffer 1, point to it 

Schedule write 

Second buffer full yet? 

Not yet, return 

Second buffer full, reset pointer 

Point to second buffer for write 

Point to EMT arg block to 
Schedule completion routine 
to write buffer to file 
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9$: 


TST 


TTSTAT 




BEQ 


10$ 




BIC 


#INTNBL,@#RCSR 


10$: 


RETURN 





;Does mainline want to quit? (TC) 

; Branch if not 

;If so, disable interrupts 

;Wait for another char 

;Note RTS PC, not RTI ! 



; Completion routine to save buffer to file 

CMPRTN: .WRITE #AREA,#0,R1,#256. , BLOCK ;Write buffer to file 

;Br if no error 
;0n error, set abort flags 

;Skip .TTYIN, and abort 

; Point to next output block 





BCC 


1$ 




MOVB 


CTRLC,INBUF 




MOV 


#-1, TTSTAT 




JMP 


WHOA 


1$: 


INC 
RETURN 


BLOCK 



; Routine to complete write of last block 



FINISH: 


MOV 


BUFPTR,R0 




MOV 


#BUFF2,R1 




CMP 


R0,R1 




BLO 


1$ 




ADD 


#2*BUFSIZ,R1 


1$: 


CLRB 


(R0)+ 




CMP 


R0,Rl 




t«t r\ 
DJ-iU 


1 <s 




SUB 


#2*BUFSIZ,R1 




CALL 


CMPRTN 




RETURN 





;Get current buffer pointer 

;Point to end of first buffer 

;See which buffer in use 

;Skip if in first 

;If in second, point to end 

;Zero out buffer 

;AL1 the way to the end 

;Now point back to buffer beginning 
;Call write routine (NOT AS COMPLETION) 



; EMT arg block areas 



AREA: 


• BijKW 


i n 


L0KJ0B : 


.BYTE 


13,140 


MAP 10: 


.BYTE 


5,140 


ACTCTD: 


.BYTE 
.WORD 
.WORD 


0,152 

D 
CTRLD 


INTSVC : 


.BYTE 
.WORD 
.WORD 
.WORD 


20,140 
VECTOR 
ISR 




SCHWRT: 


.BYTE 
.WORD 
.WORD 


21,140 
CMPRTN 
7 



;EMT arg block to lock job in mem 

;EMT arg block to map I/O page to PAR 7 

;EMT arg block to 

;Set activation character 

;Control-D 

;EMT arg block to set up interrupt svc routine 

;Vector to attach 

;Address of Interrupt Service Routine 

; Required 

;EMT arg block to sched compl routine 
;Write buffer contents to file 
;Real-time priority (adds to PRIHI) 
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WRTPTR: .WORD 
.WORD 

RELVEC: .BYTE 12,140 
.WORD VECTOR 

; General storage 



OUTSPC : 


.BLKW 


15. 


INS PC : 


.BLKW 


24. 


DEFEXT : 


.WORD 


0,0,0,0 


S PS AVE: 


.WORD 





BLOCK: 


.WORD 





TTSTAT: 


.WORD 





VECSAV: 


.WORD 





VECSV2: 


.WORD 





DEVLST: 


.WORD 


RCSR 


CSRSAV: 


.WORD 







.WORD 





BUFPTR: 


.WORD 





INBUF: 


.BYTE 


0,0,0,0 


BUFFI: 


.BLKW 


BUFSIZ 


BUFF2: 


.BLKW 


BUFSIZ 


BUFEND: 







; Passed in Rl to compl routine (buffer addr) 
; Required 

;EMT arg block to release interrupt connection 
; Vector to be released 



CSI output file specs 
CSI input file specs 
No default file specs 
Save stack pointer during CSI call 
Output file block counter 
SCCA terminal status word 
Save original vector contents 
and priority 
.DEVICE restoration list 
To hold original value of RCSR 
End of list 

Current input char pointer 
Terminal command buffer 
1 block input buffer 
Second buffer 



,END 



START 



11.11.2 Interrupt completion routines. 

The TSX-Plus real-time support facility allows a program to connect a real-time 
interrupt to a completion routine. If this is done, TSX-Plus schedules the 
completion routine to be executed each time the specified interrupt occurs. 

Interrupt completion routines have much greater flexibility than interrupt 
service routines, but require more overhead and are capable of servicing 
interrupts only at a lower rate. Interrupt completion routines run with full 
job context. This allows them to use all system service calls (except to the 
USR). Registers will be preserved between calls to the completion routine. 

Real-time completion routines can service interrupts at rates up to about 200 
interrupts per second. Devices which interrupt at a faster rate should be 
connected through an interrupt service routine or through a special device 
handler. 

The total number of interrupt vectors that can be connected either to interrupt 
completion routines or interrupt service routines is determined by the RTVECT 
parameter during TSX-Plus system generation. It is possible for several 
interrupts to be connected to the same completion routine in a job but it is 
illegal for more than one job to try to connect to the same interrupt. When an 
interrupt completion routine is entered, R0 contains the address of the 
interrupt vector that caused the completion routine to be executed. 
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Real-time completion routines, whether directly connected to an interrupt or 
scheduled with the EMT for that purpose, have an associated job priority. 
These are software priorities, not hardware priorities; all completion routines 
are synchronized with the job and execute at hardware priority level 0, 
Completion routine priorities 1 and larger are classified as "real-time" 
priorities and are added to the system parameter PRIHI to yield the job 
execution priority, unless the resultant priority would exceed 127 in which 
case the priority will be 127. These completion routines will then be 
scheduled for execution whenever there are no executable jobs with a higher 
priority. 

A real-time completion routine for one job will be suspended if an interrupt 
occurs which causes a higher priority completion routine to be queued for 
another job. However, a real-time completion routine for one job will never be 
interrupted by a completion routine for that same job regardless of the 
subsequent completion routine's priority. If additional requests are made to 
trigger the same or different completion routines while a completion routine is 
executing, the requests are queued for the job and are serviced in order based 
on their priority and the order in which they were queued. 

A real-time completion routine is allowed to run continuously until one of the 
following events occurs: 1) the completion routine finishes execution and 
returns; 2) a higher-priority completion routine from another job interrupts 
its execution — it is re-entered when the higher-priority routine exits; or 3) 
the completion routine enters a system wait state such as waiting for an I/O 
operation to complete or waiting for a timed interval. If a real-time 
completion routine enters a wait state, it returns to the same real-time 
priority when the wait condition completes. 

Real-time completion routines with a priority of are treated slightly 
differently than those with priorities greater than zero. The action taken 
depends on the priority of the main-line job when the completion routine is 
scheduled. If the base priority is equal to or greater than PRIHI, then the 
completion routine is treated just as those with real-time priorities greater 
than zero. That is, the completion routine is assigned a priority of PRIHI 
(PRIHI + the real-time priority of 0). On the other hand, if the base job 
priority is less than PRIHI, then the job is scheduled as a very high priority 
normal (non-interactive) job. The effect of this is that completion routines 
with a real-time priority of and a base job priority less than PRIHI will 
interrupt normal time-sharing jobs, but are time-sliced in the normal fashion 
and lose their high priority if they execute longer than the system parameter 
QUAN1A. 

Jobs that have real-time, interrupt completion routines need not necessarily be 
locked in memory. If an interrupt occurs while the job is swapped out of 
memory, it is scheduled for execution like any other job and swapped in before 
the completion routine is executed. Note, however, that this condition is not 
optimal for timely servicing of interrupts. 
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When a real-time interrupt occurs, a request is placed in a queue to execute 
the appropriate completion routine. If the interrupt occurs again before the 
completion routine is entered, another request is placed in the queue so the 
completion routine will be invoked twice. A TSX-Plus fatal system error occurs 
if an interrupt occurs and there are no free completion routine request queue 
entries. 

When a real-time completion routine completes its execution, it must exit by 
use of a RETURN instruction (RTS PC), not an RTI . 

The form of the EMT used to connect an interrupt to a real-time completion 
routine is: 



EMT 



375 



with RO pointing to the following argument area: 

.BYTE 11,140 

.WORD interrupt-vector 

.WORD completion-routine 

.WORD priority 

where "interrupt-vector" is the address of the interrupt vector, "completion- 
routine" is the address of the completion routine, and "priority" is the 
execution priority for the completion routine. 



Error: 



Code Meaning 




1 
2 

Example : 



Real-time support not included or job not privileged 

Maximum number of vectors already in use 

Some other job is already connected to that vector 



.TITLE ATTVEC 
.ENABL LC 



; Demonstrate TSX-Plus EMTs to attach a completion routine to an interrupt 

;Control-C 



CTRLC = 3 
ERRBYT = 52 
RCSR = 176540 
RBUF = RCSR+2 



; Serial line RCSR address 
;Line input buffer address 



.MCALL .PRINT, .EXIT, .TTYOUT, .SPND, .RSUM 



START : MOV #MAP IOP , RO 
EMT 375 
BCC 1$ 



; Point to EMT arg block to 

;Map to I/O page 

; Branch if OK to map 
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;You aren't allowed to do that 



If this job were to be resident for a long time, it would be better 
to lock into low memory to avoid memory fragmentation by job swapping. 
However, since this job may have to be swapped now to get into low 
memory, locking into low memory takes longer to execute. 

; Point to EMT arg block to lock into low mem. 

; Point to EMT arg block to 
;Lock the job in memory 

; Point to EMT arg block to 

;Attach to an interrupt vector 

;Continue if OK 

; Notify can't attach to interrupt 

;Find out which error 

; Convert to word offset 

;And explain reason for error 

;Go on to unlock and exit 

;Prompt for input from interrupting device 
;Now wait for an interrupt 

; Resume uere on exit from completion coue 
; Point to EMT arg block to 
;Release an Interrupt vector 

NOTE: Any interrupts through this vector after it has been released 

will cause a TSX-Plus fatal system error - Unexpected Interrupt. 



;i$: 


MOV 


#LOKLOW,R0 


1$: 


MOV 


#L0KJ0B,R0 




EMT 


375 




MOV 


#ATTVEC,R0 




EMT 


375 




BCC 


2$ 




.PRINT 


#BADATT 




MOVB 


@#ERRBYT,R0 




ASL 


RO 




.PRINT 


ATTERR(RO) 




BR 


3$ 


2$: 


.PRINT 


#TYPE 


j . . « 


.SPND 






MOV 


#RELVEC,R0 




EMT 


375 



'$: 



MOV 
EMT 
.EXIT 



375 



; Unlock this job from memory 



The following code will be executed as a completion routine 
when the device attached to the vector interrupts. 



;Enter here when new character is available 

[Get the new character 

[Should we quit? 

;Quit on "C 

[Display the character 

1 Point to EMT arg block to 

;Set processor priority (block interrupts) 

[Time critical processing goes here 

[Set priority back down 



CMPRTN: MOVB 


@#RBUF,R0 


CMPB 


R0,#CTRLC 


BEQ 


1$ 


.TTYOUT 




MOV 


#SETPRI,R0 


EMT 


375 



CLR 



PRILEV 






Real-Time Programs 



1$: 
2$: 



MOV 

EMT 

BR 

.RSUM 

RETURN 



#SETPRI,R0 

375 

2$ 



; Point to EMT arg block to 

;Set processor priority (reenable interrupts) 

;Return to main-line code 

;Wait for next interrupt (NOTE: Not RTI) 



EMT arg block to map to I/O page 

EMT arg block to lock job into low mem. 

EMT arg block to lock job in place 

EMT arg block to unlock job from memory 

EMT arg block to attach to interrupt 

Interrupt vector 

Address of completion routine 

Real-time priority (NOT processor priority!) 

EMT arg block to release interrupt vector 

Interrupt vector 

EMT arg block to set processor priority 

Desired priority level (modifiable) 

Attach to interrupt error table 



MAPIOP: .BYTE 5,140 

LOKLOW: .BYTE 7,140 

L0KJ0B: .BYTE 13,140 

UNLOKJ: .BYTE 10,140 

ATTVEC: .BYTE 11,140 

.WORD 340 

.WORD CMPRTN 

.WORD 7 

RELVEC: .BYTE 12,140 

.WORD 340 

SETPRI: .BYTE 16,140 

PRILEV: .WORD 7 

ATTERR: .WORD NOPRIV 

.WORD MAXINT 

.WORD INUSE 

.NLIST BEX 

TYPE: .ASCIZ /Characters entered on serial line will be displayed here:/ 

BADATT: .ASCIZ /?ATTVEC-F-Cannot attach to interrupt. /<7> 

NOPRIV: .ASCII /Real-time support not specified during TSGEN or / 

.ASCIZ /user not privileged./ 

MAXINT: .ASCIZ /Maximum number of interrupts already in use./ 

INUSE: .ASCIZ /Another job already connected to interrupt./ 

.END START 



11.12 Releasing an interrupt connection 

A connection between an interrupt vector and an interrupt service routine or an 
interrupt completion routine remains in effect until the job exits or the 
following EMT is executed to release the connection. 

Warning : An interrupt through a vector which has been released with this EMT or 
which was connected to a job that has terminated will cause a fatal system 
error: UEI-Interrupt occurred at unexpected location. 

The form of the EMT is: 



EMT 



375 



with R0 pointing to the following argument area: 

.BYTE 12,140 

.WORD interrupt-vector 
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where "interrupt-vector" is the address of the interrupt vector whose connec- 
tion is to be released. An error will cause the carry-flag to be set on 
return, indicating that either real-time support was not included in the 
TSX-Plus generation or the job does not have operator privilege. 

Example: 

See the example program ATTVEC in the section on connecting a real-time 
interrupt to a completion routine. 



11. 13 Scheduling a. completion routine 

Real-time programs may schedule a completion routine for execution with a 
special EMT provided for that purpose. This is particularly valuable from 
within interrupt service routines which do not have access to system service 
calls other than this EMT and the .RSUM request. While any program with 
real-time (operator) privilege may issue this request, its primary intent was 
to provide a mechanism for access to system service calls from interrupt 
service routines. The form of this EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 21,140 

.WORD completion-routine 

.WORD priority 

.WORD Rl- value 

.WORD 

where "completion-routine" is the address of the entry point of the completion 
routine that is being started, "priority" is the real-time priority level for 
the completion routine being started, and "Rl-value" is a value to be placed in 
Rl on entry to the completion routine. 

Completion routines scheduled in this manner follow the same rules as for 
interrupt completion routines described above, except that they are scheduled 
as a result of the EMT call rather than in response to an interrupt. 

Example : 

See the example program INTSVC in the section on connecting interrupts to 
real-time jobs/ interrupt service routines. 
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11. 14 Adapting real-time programs to TSX-Plus 

The following points should be kept in mind when converting an RT-11 real-time 
program for use under TSX-Plus. 

1. The I/O page (160000-177777) is not directly accessible to the program 
unless the program executes the TSX-Plus real-time EMT that maps the job's 
virtual region to the I/O page. 

2. If the program's virtual region 160000 to 177777 is mapped to the I/O 
page, the program must use .GVAL to access offsets in the simulated RMON. 

3. Real-time interrupts are connected to interrupt service routines and 
interrupt completion routines by use of the TSX-Plus real-time EMT for 
that purpose. The program should not try to connect interrupts by storing 
into the interrupt vector cells. 

4. The .PROTECT EMT is a no-op under TSX-Plus and always returns with the 
carry-flag cleared. 

5. Interrupt service routines and completion routines connected to real-time 
interrupts should exit by use of a RTS PC instruction rather than RTI. 

6. Programs that require very rapid response to interrupts should use the 
interrupt service routine method and must lock themselves in memory. 

7. Real-time interrupts must not occur unless an interrupt service routine or 
completion routine is connected to the interrupt. If a real-time 
interrupt occurs with no associated interrupt service or completion 
routine, a fatal TSX-Plus system error (UEI) occurs and the "argument 
value" displays the address of the vector of the interrupt. 

8. A higher priority real-time completion routine for one job will interrupt 
a lower priority completion routine being executed by another job but will 
not interrupt a lower priority completion routine being executed by the 
same job. 

9. A real-time completion routine running at priority 1 or above is not 
time-sliced and will lock out all lower priority jobs until it completes 
its processing or enters a wait state. 
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TSX-Plus provides a facility that allows one or more shared run-time systems or 
data areas to be mapped into the address space of multiple TSX-Plus time- 
sharing jobs. There are two primary uses of this facility: 

1. Memory space can be saved by having multiple jobs that use the same 
run-time system access a common copy rather than having to allocate 
space within each job for a copy. 

2. Programs can communicate with each other through the use of a common 
shared memory region to which all of the communicating jobs have 
direct access. 

To use this facility, information about all of the shared run-time systems must 
be declared when the TSX-Plus system is generated. During system initializ- 
ation the shared run-time system files are opened and read into memory. These 
shared run-time systems remain in memory as long as the system is running and 
are never swapped out of memory even if there are no jobs actively using them. 

The EMTs described below can be used to associate one or more shared run-time 
systems with a job. When such an association is made, a portion of the job's 
virtual memory space is mapped to allow access to part or all of one or more 
run-time systems. 

12.1 Associating a. run- time system with a job 

The following EMT is used to associate a shared run-time system with a job. 
The form of the emt is: 

t?mt 7.1 ^ 

with RO pointing to the following argument area: 

.BYTE 0,143 

.WORD name-pointer 

where "name-pointer" is the address of a two-word cell containing the six 
character name of the shared run-time system in RAD50 form. This name 
corresponds to the file name which was specified for the run-time system when 
TSX-Plus was generated. If the name pointer value is zero, the effect of the 
EMT is to disassociate all shared run-time systems from the job and to 
re-establish normal memory mapping for the job. 

If the run-time system whose name Is specified with this EMT is not recognized, 
the carry-flag is set on return with an error code of 1. 

The effect of this EMT is to associate a particular shared run-time system with 
the job. However, this EMT does not affect the memory mapping for the job or 
make the run-time system visible to the job; that is done by the EMT described 
below. If some other run-time system has been previously mapped into the job's 
region, that mapping is unaffected by this EMT. Thus it is possible to have 
multiple run-time systems mapped into the job's region by associating and 
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mapping them one at a time into different regions of the job's virtual memory 
space. 



Example 


j 






.TITLE 


USERTS 




.ENABL 


LC 


; Demonstration 


of TSX-Plus EMT 




.MCALL 


.PRINT, .EXIT 


PARI 


= 20000 




START : 


MOV 


#USERTS,R0 




EMT 


375 




BCC 


1$ 




.PRINT 


//NOSHRT 




.EXIT 




1$: 


MOV 


#MAPRTS,R0 




EMT 


375 


2$: 


CALL 


@#<PARl+200> 




CLR 


SHRNAM 




CLR 


<SHRNAM+2> 




MOV 


#USERTS,R0 




EMT 


375 


; . . . 


.EXIT 




USERTS: 


.BYTE 


0,143 




.WORD 


SHRNAM 


SHRNAM: 


.RAD50 


/RTCOM / 


MAPRTS : 


.BYTE 


1,143 




.WORD 


1 




.WORD 







.WORD 


1000/64. 




.NLIST 


BEX 


NOSHRT: 


.ASCIZ 


/Can't find the 




.END 


START 



to map to a shared run-time region 

;Base address of PAR 1 window 

; Point to EMT arg block to 

;Associate a shared run-time region 

;Error? 

; Can't find named shared run-time 

; Point to EMT arg block to 
;Map to shared run- time system 
;JSR to entry point in shared region 
; which prints some data from there. 
;Undeclare any shared run- times 

; Point to EMT arg block to 
;Dissociate all shared regions 
;Go on with other processing 

;EMT arg block to associate 

; Pointer to file name 

; Shared region file name 

;EMT arg block to map shared region 

;Map PAR 1 

;0ffset Into region 

;Size of region (64. byte blocks) 

shared run- time system. /<7> 



The example program RTCOM declared in the above program was defined during 
TSX-Plus system generation with the RTDEF macro as follows: 

RTDEF <SY RTCOM SAV>,RW,1 

and the shared program itself was: 

.TITLE RTCOM 

.ENABL LC 
; Demonstration shared run-time file 
; (Position Independent Code.) 

.MCALL .PRINT 

.NLIST BEX 

.PSECT RTCOM, I ;RTDEF in TSGEN specifies 
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;skip 1 block so default start address of 1000 is OK 
START: .ASCII /This data was produced by the / 

.ASCIZ /RTCOM shared run-time region./ 

. = START + 200 ;Entry point for shared code 
ENTRY:: MOV PC,R0 ;Find out where we are 

SUB #<.-START>,R0 ; Point back to data area 

.PRINT R0 ; Display what is there 

RETURN ;And go back to MAIN 

•END ENTRY 

12.2 Mapping a run-t ime system into a. job"s region 

Once a shared run-time system has been associated with a job by use of the 
previous EMT, the run-time system (or a portion thereof) can be made visible to 
the job by mapping it into the job's virtual address region. The form of the 
EMT to do this is: 

EMT 375 

with R0 pointing to the following argument area: 



.BYTE 


1,143 


.WORD 


par-region 


.WORD 


run-time-offset 


.WORD 


mapped-size 



The "par-region" parameter is a number in the range to 7 that indicates the 
Page Address Register (PAR) that is to be used to access the run-time system. 
The PAR number selects the region of virtual memory in the job that will be 
mapped to the run-time system. The following correspondence exists between PAR 
numbers and virtual address regions within the job: 

PAR Address Range 



000000 - 017777 

1 020000 - 037777 

2 040000 - 057777 

3 060000 - 077777 

4 100000 - 117777 

5 120000 - 137777 

6 140000 - 157777 

7 160000 - 177777 



The "run-time-offset" parameter specifies which portion of the run-time system 
is to be mapped into the PAR region. The "run-time-offset" specifies the 
number of the 64-byte block within the run- time system where the mapping is to 
begin. This makes it possible to access different sections of a run-time 
system at different times or through different regions. 
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The "mapped-size" parameter specifies the number of 64-byte blocks to be 
mapped. If this value is larger than can be contained within a single PAR 
region, multiple PAR regions are automatically mapped as necessary to contain 
the entire specified section of the run-time. 

If an error is detected during execution of the EMT, the carry-flag is set on 
return with an error code of 1 to indicate that there is no run-time system 
associated with the job. 

This EMT only affects the mapping of the PAR region specified in the argument 
block (and following PAR's if the size so requires). It does not affect the 
mapping of any other PAR regions that may previously have been mapped to a 
run-time system. Thus a job may have different PAR regions mapped to different 
sections of the same run-time system or to different run-times. Real-time 
programs may map PAR 7 to the I/O page and also map other PAR regions to shared 
run-time systems. 

The memory size of a job is not affected by the use of the shared run-time 
control EMTs. That is, mapping a portion of a job's virtual address space to a 
shared run-time system neither increases nor decreases the size of memory 
occupied by the job. If a job's size is such that a portion of its normal 
memory is under a PAR region that is mapped to a run-time system, that section 
of its normal memory becomes inaccessible to the job as long as the run-time 
system mapping is in effect, but the memory contents are not lost and may be 
re-accessed by disassociating all run-time systems from the job. 

Note that any of the PAR regions may be mapped to a run-time system including 
PAR 7 (160000-177777). 

Example: 

See the example program USERTS in the section on associating a run-time system 
with a job. 
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13. TSX-Plus PERFORMANCE MONITOR FEATURE 



TSX-Plus includes a performance analysis facility that can be used to monitor 
the execution of a program and determine what percentage of the run time is 
spent at various locations within the program. During performance analysis, 
TSX-Plus examines the program being monitored when each clock tick occurs (50 
or 60 times per second) and notes at what location in the program execution is 

taking place. Once the analysis is completed the TSX-Plus performance 
reporting program (TSXPM) can be used to produce a histogram showing the 
percentage of time spent at various locations during the monitored run. 

There are three steps involved in performing a performance analysis on a 
program: 

1. Use the MONITOR command to begin the analysis. 

2. Run the program to be monitored. 

3. Run the TSXPM program to print a histogram of the result. 

13.1 Starting a. performance analysis 

The first step in doing a performance analysis is to use the MONITOR keyboard 
command to tell TSX-Plus that a performance analysis is to be done on the 
program that will be run next. The form of the MONITOR command is: 

MONITOR base-address, top-address [ , cell-size] /switches 

where "base-address" is the lowest address in the region to be monitored, 
"top-address" is the highest address in the region to be monitored, and 
"cell-size" is an optional parameter that specifies the number of bytes of 
address in the region being monitored to be grouped together into each 
histogram cell. If the "cell-size" parameter is not specified, TSX-Plus 
calculates the cell size by dividing the number of bytes in the region being 
monitored (base-address to top-address) by the total number of histogram cells 
available (specified when TSX-Plus is generated). This gives the finest 
resolution possible. The only available switch is "/I" which causes I/O wait 
time to be included in the analysis. If this switch is not specified, only CPU 
execution time is included in the analysis. A link map of the program should 
be available to determine the addresses in the program that are appropriate to 
monitor. 

Examples: 

. MONITOR 1000,13000/1 

. MONITOR 20000,40000,10 

. MONITOR 2000,6000 

The effect of the MONITOR command is to set up parameters within TSX-Plus which 
will be used to monitor the next program run. It does not actually begin the 
analysis, so there is no rush in running the program to be monitored. Once the 
MONITOR command has been issued, the program to be monitored is run by using 
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the standard "RUN" or "R" commands. If a program being monitored does a .CHAIN 
to another program, the analysis continues and the times reported will be the 
composite of the programs run. 

Only one user may be doing a performance analysis at a time. This is because 
the performance analysis histogram buffer is a common memory area that may not 
be in use by more than one user at a time. An analysis is in effect for a user 
between the time the MONITOR command is issued and the TSXPM program is run to 
display the results of the analysis. Running the TSXPM program terminates the 
performance analysis and allows other users to perform analyses. Note that 
space for the performance analysis data buffer must be reserved when TSX-Plus 
is generated. 

If the program to be monitored is overlayed and the region to be monitored is 
in the overlay area, the analysis technique is more complex. In this situ- 
ation, the EMTs described below must be used to control the performance 
analysis as overlay segments are run in the segment being monitored. 

13.2 Displaying the results of the analysis 

After the program being monitored has exited and returned control to the 
keyboard monitor, the TSXPM performance reporting program is used to generate a 
histogram of the time spent in the region being monitored. The TSXPM program 
is started by typing "R TSXPM"; it responds by printing an asterisk ("*"). In 
response to the asterisk, enter the file specification for the device/file 
where the histogram is to be written. An optional switch of the form "/M:nnn" 
may be specified following the file specification. This switch is used to 
specify the minimum percentage of the total run-time that a histogram cell must 
contain in order to be included in the display. If this switch is not 
specified, the default cut-off percentage is 1%. 

After receiving the file specification, TSXPM prompts for a title line. Enter 
a line of text which will be printed as a page title in the histogram file. 
Press RETURN if you wish no title. 

The next item of information requested by TSXPM is a set of base offset values. 
The base offset values are optional. Base offsets are useful in the situation 
where you have several modules making up a program being monitored and you want 
the addresses displayed on the performance analysis histogram to be relative to 
the base of each module. You may specify up to 10 offset values. Each offset 
value is specified as an offset module number (in the range to 9) followed by 
a comma and the base address of the module (see example below). If offset 
values are specified, TSXPM determines in which module each cell of the 
histogram falls and displays the address as a module number and offset within 
the module. After you enter all desired module offsets, enter RETURN without a 
value . 

After the base offset values are entered, the histogram will be produced and 
written to the specified device and file. After the histogram is generated, 
TSXPM prints the asterisk prompt again, at which point you may enter the name 
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of another device/file and produce the histogram again or you may type 
control — C to return to the keyboard monitor* 

Example use of TSXPM: 

.R TSXPM 

*LP;/M:5 

Title: PERFORMANCE ANALYSIS OF EIGENVALUE CALCULATION 

Base offsets: 

XL, 1000 

>2,2134 

>3,5212 

> 

(Histogram is produced at this point) 
* <CTRL-C> 

The histogram produced by TSXPM consists of one line per histogram cell. Each 
line contains the following information: 1) the base module offset number (if 
offsets were specified); 2) the address range covered by the histogram cell 
(relative to the module base if base offsets were used); 3) the percentage of 
the total execution time spent at the address range covered by the histogram 
cell; 4) a line of stars presenting a graphic representation of the histogram. 

13.3 Performance monitor control EMT^s 

r u i. uiusL appj.j.^atxuua i_nc uictuuu ucdi, i. j-dcu. auuvc (~<aii uc uocu iu uu ci ^ciiului 

ance analysis. However, in special cases (such as analyzing the performance of 
an overlayed program) it is necessary to have more explicit control over the 
performance analysis feature as a program is running. The following set of 
EMTs may be used to control a performance analysis. 

13.3. 1 Initializing a_ performance analysis . 

TV> ■? o TTMT -? e iiaaA t-n cat- un riarampt'prc <-Viot- ui 1 1 <->r»-n i-ml a norformanoo qnalwoi o. 

It does not actually begin the analysis. The form of the EMT is: 

EMT 375 
with R0 pointing to the following argument block: 



.BYTF 


0,136 


.WORD 


base-address 


.WORD 


top-address 


.WORD 


cell-size 


.WORD 


flags 



where "base-address" is the address of the base of the region to be nonitored, 
"top-address" is the address of the top of the region to be monitored, and 
"cell-size" is the number of bytes to group in each histogram cell. If 
(zero) is specified as the cell size, TSX-Plus calculates the cell size to use 
by dividing the number of bytes in the region being monitored (top-address 
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minus base-address) by the number of cells available in the histogram data area 
(specified when TSX-Plus is generated). The "flags" parameter is used to 
control whether or not I/O wait time is to be included in the analysis. If a 
value of 1 is specified as the "flags" parameter, I/O wait time is included in 
the analysis; if a value of (zero) is specified, I/O wait time is not 
included in the analysis. 



Errors: 



Code Meaning 



Performance analysis being done by some other user. 

Performance analysis feature not included in TSX-Plus generation, 



Example: 



.TITLE DEMOPA 
.ENABL LC 

Demonstrate use of TSX-Plus EMT's to initialize, start, stop, and 
terminate a performance analysis 

.MCALL .EXIT, .PRINT, .LOOKUP, .READW, .CLOSE, .TTYOUT 

.GLOBL PRTOCT ; Display an octal word in RO 



ERRBYT = 52 
SPACE = 40 
STAR = 52 



EMT error byte 
ASCII 'space' 
ASCII 'asterisk' 



START: 



5$: 



10$; 



MOV 


#INITPA,R0 


EMT 


375 


BCC 


5$ 


MOVB 


@#ERRBYT,R0 


ASL 


RO 


.PRINT 


INIERR(RO) 


.EXIT 




MOV 


#STRTPA,R0 


EMT 


375 


BCC 


10$ 


.PRINT 


#STRERR 


.EXIT 





; Point to EMT arg block to 

; Initialize the performance analysis 

;No error 

;Which error? 

; Convert to word offset 

;Print the error message 

;And depart this world of woe. 

; Point to EMT arg block to 

; Start the performance analysis 

;No error 

; Start error 

;and depart. 



; Dummy section of code to do some I/O and computation for analysis 

BEGIN: .LOOKUP //AREA, #0,#FILNAM 

MOV #10, Rl 
; Disk I/O 

1 $ : . READW #AREA, #0 , //BUFFER, #256 . , #0 

SOB Rl,l$ 

. CLOSE #0 
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; Terminal I/O 

.PRINT //BUFFER 

; Compute bound 

MOV #123456, R3 

2$: MOV #1234 5, RO 
CLR Rl 
DIV #345, RO 
SOB R3,2$ 

ENDB: 

NCELLS = «ENDB-BEGIN>/2> 



;Number of cells in histogram 





MOV 


#STOBLK,RO 




EMT 


375 




BCC 


15$ 




.PRINT 


#STOERR 




.EXIT 




15$: 


MOV 


#HALBLK, RO 




EMT 






BCC 


20$ 




MOVB 


@#ERRBYT,R0 




ASL 


RO 




.PRINT 


HLTERR(RO) 




.EXIT 




20$: 


TST 


HALFLG 




BPL 






.PRINT 


#OVRWRN 


25$: 


BIT 


#1 , HALFLG 




BEQ 


30$ 




. PRINT 


#IOWNOT 


; Print 


a histogram of the per 


30$: 


CLR 


R3 


35$: 


CMP 


HSTTBL(R3),#64 




BHI 


40$ 




ADD 


#2,R3 




CMP 


R3,#<2*NCELLS> 




BLE 


35$ 




BR 


50$ 


40$: 


CLE 


R3 


45$: 


CLC 






ROR 


HSTTBL(R3) 




ADD 


#2,R3 




CMP 


R3,#<2*NCELLS> 




BLE 


45$ 




BR 


30$ 


50$: 


. PRINT 


#HSTMSG 




MOV 


#BEGIN,R2 




CLR 


R3 


55$: 


MOV 


R2,R0 



; Point to EMT arg block to 

;Stop the performance analysis 

; Check for error return 

;Only one error - PA not initialized 

;and leave. 

Put HALTPA block address in RO 

Terminate the performance analysis 

Check for errors 

Get error type 

Convert to word offset 

Print out proper error message 

And depart. 

Check HALTPA return flag 

No cell overflow? 

Issue overflow warning 

1/0 time included? 

Skip message if not 

Print 1/0 wait time included msg 



analysis 
*Set histogram cell counter 
; Normalize the table for 64. longest 
;Too many counts? 
; Point to next cell 
;End of table? 
;No, repeat 

;A11 cells less than 64. counts now 
;Re-init. histogram cell counter 
;Divide each cell count by 2 

; Point to next cell 

;End of table? 

;No, repeat 

;Go check all cells again 

;Caption histogram 

;Set first analyzed address 

;Init. cell counter 

;Get ready to print it out 
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60$: 
65$: 



INITPA: 



STRTPA : 
STOBLK: 
HALBLK: 



PRMBUF 

HALFLG 

HSTTBL 

HSTEND 

AREA: 

BUFFER: 

FILNAM: 
INIERR: 

HLTERR: 



INPRG: 

NOGEN: 

NOPA: 

TOSMAL: 

STRERR: 

STOERR: 

OVRWRN: 

IOWNOT: 

OKDONE: 

HSTMSG: 

CRLF: 



CALL 

. TTYOUT 

MOV 

BEQ 

.TTYOUT 

SOB 

. PRINT 

CMP 

CMP 

BLE 

.EXIT 

.BYTE 
.WORD 
.WORD 
.WORD 
.WORD 
.BYTE 
.BYTE 
.BYTE 
.WORD 
.WORD 
.WORD 
.BLKW 
.WORD 
.BLKW 

.BLKW 

.BLKW 

.WORD 

.RAD50 

.WORD 

.WORD 

.WORD 

.WORD 

.NLIST 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



PRTOCT 

//SPACE 

HSTTBL (R3),R1 

65$ 

//STAR 

Rl,60$ 

//CRLF 

(R2)+,(R3)+ 

R3,//<2*NCELLS> 

55$ 



0,136 

BEGIN 

ENDB-2 

2 

1 

1,136 

2,136 

3,136 

PRMBUF 

HSTTBL 

<HSTEND-HSTTBL> 

3 



<2*NCELLS>+2 



;Display analyzed address 
;For formatting 
;Get address use counter 
;No stars on count 
;Print a '*" for each count 

;Go to next line 

; Point to next address and count 

;End of histogram? 

;No, display next cell 

;Else done. 

EMT arg block for perform, analysis 

Start analysis address 

End analysis address 

Count 1 address in each cell 

Include 10 wait time. 

Start Performance Analysis EMT block 

EMT arg block to stop perf. analysis 

EMT arg block to release analysis 

PA parameter buffer address 

Histogram Table buffer address 

Histogram Table buffer length 

PA four word parameter buffer 

PA return flags 

Histogram table 



;EMT arg block area 
;Data input buffer 
;Make sure buffer is ASCIZ 
;Read this file 
jlnitialize PA error table 

;HALTPA Error message table 



10 

256. 



/DK DEMOPAMAC/ 

INPRG 

NOGEN 

NOPA 

TOSMAL 

BEX 

/?INITPA-F -Performance analysis being done by another user./ 

/7INITPA-F -Performance analysis feature not genned./ 

/?HALTPA-F-This job is not doing a performance analysis./ 

/?HALTPA-F-Area provided for histogram table too small./ 

/7INITPA-F -Performance analysis not initialized yet./ 

/?ST0PPA-F -Performance Analysis has not been initialized./ 

/?HALTPA-W-Some histogram cell(s) overflowed during analysis./ 

I HALTPA-I-I/0 wait time included in performance analysis. I 

/ STOPPA-S-Performance Analysis stopped./ 

/Address Frequency/ 

<15><12X200> 

START 
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13.3.2 Starting a_ performance analysis. 

This EMT is used to begin the actual collection of performance analysis data. 
The previous EMT must have been executed to set up parameters about the 
performance analysis before this EMT is called. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 1,136 

The carry-flag will be set on return from this EMT if performance analysis has 
not been initialized yet. 

Example: 

See the example program DEMOPA in the section on initializing a performance 
analysis. 

13.3.3 Stopping a. performance analysis. 

The following EMT can be used to suspend the data collection for a performance 
analysis. The data collection can be restarted by using the start-analysis EMT 
described above. This EMT could, for example, be used to suspend the analysis 
when an overlay module is loaded that is not to be monitored. The start- 
analysis EMT would then be used to re-enable the data collection when the 
overlay of interest is re— loaded. The form of this EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 2,136 

The carry flag will be set on return from this EMT if performance analysis has 
not been initialized yet. 

Example: 

See the example program DEMOPA in the section on initializing a performance 
analysis. 

13.3.4 Terminating a. performance analysis. 

This EMT is used to conclude a performance analysis. It has the effect of 
returning into a user supplied buffer the results of the analysis and releasing 
the performance analysis feature for other users. The form of this EMT is: 
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EMT 375 

with RO pointing to the following argument block: 

.BYTE 3,136 

.WORD parameter-buffer 

.WORD histogram-buffer 

.WORD buffer-size 

where "parameter-buffer" is the address of a 4 word buffer into which will be 
stored some parameter values describing the analysis that was being performed, 
"histogram-buffer" is the address of the buffer that will receive the histogram 
count values, and "buffer-size" is the size (in bytes) of the histogram buffer 
area . 

The values returned in the parameter buffer consist of the following 4 words: 
1) base address of the monitored region; 2) top address of the monitored 
region; 3) number of bytes per histogram cell; 4) control and status flags. 
The control and status flags are a set of bits that provide the following 
information: 

Flag Meaning 



1 I/O wait time was included in the analysis. 
100000 Some histogram cell overflowed during the analysis. 

The data returned in the histogram buffer consists of a vector of 16-bit binary 
values, one value for each cell in the histogram. The first value corresponds 
to the histogram cell that starts with the base address of the region that was 
being monitored. 

Errors: 

Code Meaning 

This job is not doing a performance analysis. 

1 Area provided for histogram count vector is too small. 

Example: 

See the example program DEM0PA in the section on initializing a performance 
analysis. 
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14. TSX-Plus RESTRICTIONS 



14.1 System service call (EMT) differences between RT-11 and TSX-Plus 

The following list describes the differences in the way TSX-Plus implements 
some RT-11 system service calls (EMTs). If an EMT is not listed, it provides 
the same functions as described in the RT-11 Programmer's Reference Manual. 

.ABTIO Action depends on setting of IOABT system parameter. If IOABT is set 
to 1 then .ABTIO operates the same as RT-11 and calls handler abort 
entry points. If IOABT is set to then .ABTIO does not call handler 
entry points, but instead does a .WAIT on all channels. The default 
method of handling I/O abort requests is chosen during TSX-Plus 
system generation with the IOABT parameter. The I/O abort handling 
method may also be changed while TSX-Plus is running with the SET 10 
[NO] ABORT keyboard command. 

.CDFN User jobs may not define more than 16 channels. If a .CDFN EMT is 
done, all channels are purged if a .CHAIN is done. If .CDFN is not 
done, channels are not purged across a chain. 



uriLiuri wot implemented. 
Not implemented. 



, CNTXSW 
■DEVICE 
■FETCH 



Operator privilege is required to use this EMT. 

Returns in RO the address specified for the handler load area. All 
TSX— Plus device handle 1 ** 3 a**e reside" *■ hpnpo i-h<=» .VFTfiH RMT nprfnrniB 
no operation. If the device handler specified was not loaded during 
TSX-Plus initialization, then an error code of is returned. 



FORK May be used in device handlers but not in user jobs. 

-GTJB The job number returned in word 1 of the result area is two times the 
TSX— Plus line number * That is, the first line specified in the 
system generation will be number 2, the second 4, etc. Words 8 
through 12 of the result area are not altered by this EMT. 

.HRESET Action depends on setting of IOABT system generation parameter. If 
IOABT is set to 1 then .HRESET calls handler abort entry points. If 
IOABT is set to then .HRESET does not call handler entry points but 
instead does a .WAIT on all channels. Messages queued on named 
message channels are not canceled. Otherwise, this EMT operates the 
same as under RT-11. 

. INTEN May be used in device handlers but not in user jobs. 

.LOCK The TSX-Plus file management module (USR) is always "resident" and 
the .LOCK EMT is ignored. 

.MTxxxx Multi- terminal control EMT's (.MTIN, .MTOUT, .MTPRNT, etc.) are not 
supported. 
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.MTPS The processor priority level may not be changed from user mode, hence 
this macro performs no operation. TSX-Plus provides a special 
real-time EMT to set the processor priority. 



,MWAIT Not supported, 
communication. 



See the chapter that describes inter-job message 



PEEK Non-privileged jobs may use .PEEK to access cells within the 
simulated RMON (addresses 160000 to 160626) although the .GVAL EMT is 
a recommended alternative. Jobs with operator privilege may use 
.PEEK to access the 1/0 page or low memory cells in kernel space. 
References to addresses in the virtual address range of the simulated 
RMON (160000 to 160626) are always directed to RMON rather than the 
1/0 page. 

POKE Non-privileged jobs may use .POKE to access cells within the 
simulated RMON (addresses 160000 to 160626) although the .PVAL EMT is 
a recommended alternative. Jobs with operator privilege may use 
.POKE to access the 1/0 page or low memory cells in kernel space. 
References to addresses in the virtual address range of the simulated 
RMON (160000 to 160626) are always directed to RMON rather than the 
1/0 page. 



PROTECT Not supported. See the chapter on real-time programming 
information about how to connect an interrupt to a TSX-Plus job. 



for 



QSET 



TSX-Plus uses an internal pool of 1/0 queue elements for all jobs 
hence it is not necessary to define additional I/O queue elements in 
order to perform overlapped I/O. The .QSET EMT is ignored. 



RCVD 



Not supported, 
communication. 



See the chapter that describes inter-job message 



RELEAS This EMT is ignored. Refer to .FETCH. 



SETT0P 



SDAT 



Returns the job limit in R0 but does not actually expand or contract 
the allocated job region. The job region allocation can be changed 
by use of the MEMORY keyboard command or the TSX-Plus specific EMT 
for this purpose. 



Not supported, 
communication. 



See the chapter that describes inter-job message 



SFPA This EMT functions the same as RT-11. It must be used if a job is 
going to use the floating-point unit. 

■SDTTM Operator privilege is required to use this EMT. 

SRESET Messages queued on named message channels are not canceled. 
Otherwise, this EMT operates the same as under RT-11. 
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Restrictions 

.SYNCH May be used in handlers but not in user jobs. When used in a 
handler j the number of the TSX-Plus job that is being synchronized 
with must be stored in word 2 of the SYNCH block. 

.TLOCK This EMT is ignored. 

.TTINR Only honors bit 6 in the Job Status Word (TCBIT$) if a SET TT NOWAIT 
command has been issued, or the running program has send the "U" 
program controlled terminal option to the system, or the program was 
R[UN] with the /SINGLECHAR switch. 

.UNLOCK This EMT is ignored. 

.UNPROT Not supported. See the chapter on real-time programming for 
information about how to connect an interrupt to a TSX-Plus job. 

A full list of RT-11 compatible and TSX-Plus specific EMTs is included in 
Appendix D. The list indicates the level of support TSX-Plus provides for each 
RT-ii compatible EMT. 

14.2 Programs Not Supported by TSX-Plus 

Most programs which run under RT-11 will run under TSX-Plus without change. 
However, a modified version of ODT ("TSODT" — supplied with TSX-Plus) must be 
used to debug programs under TSX-Plus. 

The FORMAT program may not be used under TSX-Plus. 

The BATCH RT-11 facility is not supported by TSX-Plus. 

The logical subset disk feature is provided internally to TSX-Plus and 
therefore does not use the LD pseudo-device handler. 

The single line editor feature is provided as an optional system overlay region 
with TSX-Plus and does not use the SL pseudo-device handler. 

The VM handler supplied with TSX-Plus was written specially for use with 
TSX-Plus and is not the same as the DEC VM handler. 

The QUEUE package (QUEUE and QUEMAN) is not supported by TSX-Plus. 

The RESORC utility is not supported. 
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Appendix A ™ SETSIZ PROGRAM 

The SETSIZ program can be used to store into a SAV file information about how 
much memory space should be allocated for the program when it is executed. 
SETSIZ can also be used to set the "virtual job" flag in the job status word 
(JSW) for a program e 

There are three ways that the amount of memory allocated to a job can be 
controlled: 

1. The TSX-Plus EMT with function code 141 (described in Chapter 7) may be 
used by a running program to dynamically set the job's size. 

2. If a size is specified in a SAV file (by use of the SETSIZ program) the 
specified amount of memory is allocated for the program when it is 
started. 

3. If no size is specified in the SAV file, the size specified by the last 
MEMORY keyboard command is used. 

Note that the .SETTOP EMT does not alter the amount of memory space allocated 
to a job but can be used by a running program to determine the amount of memory 
allocated. 

The effect of the SETSIZ program is to store into location 56 of block of the 
SAV file the number of K-words of memory to allocate for the program when it is 
run (the LINK "/K:n" switch can also be used to do this). This value has no 
effect when the SAV file is run under RT-11 but causes TSX-Plus to allocate the 
specified amount of memory when starting the program. 

If a size value is specified in a SAV file, it takes precedence over the size 
specified by the last MEMORY keyboard command. The TSX-Plus EMT with function 
code 141 may still be used to dynamically alter the memory allocation while the 
program is running. 

Most programs allocate memory in two ways: 1) a static region that includes 
the program code and data areas of fixed size; ^.j a dynamic region that is 
allocated above the static region — usually the .SETTOP EMT is used to 
determine how much dynamic space is available to the program. The size of the 
static region for a program is fixed at link time. If the program is overlayed 
the static region includes space for the largest overlay segment as well as the 
program root. Location 50 in block of the SAV file is set by the linker to 
contain the address of the highest word in the static region of the program. 

The amount of memory space to allocate for a SAV file can be specified to the 
SETSIZ program in either of two ways: 1) as the total amount of memory for the 
program which includes space for the static plus dynamic regions; or 2) as the 
amount of memory for the dynamic region only, in which case SETSIZ automatic- 
ally adds the size of the static region. 
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A.l Running the SETSIZ program 

The SETSIZ program is started by use of the command 

.R SETSIZ 

it responds by printing an asterisk to prompt for a command line. The form of 
the command line is: 

*f ilespec/swi tch : value 

Where "filespec" is a file specification of the standard form dev:name.ext with 
the default device being "DK"and the default extension being "SAV". 

If a file specification is entered without a switch, the effect is to cause 
SETSIZ to display information about the size of the SAV file; the SAV file is 
not altered. 

SETSIZ also displays the following status message if the SAV file is flagged as 
being a virtual image. 

Virtual-image flag is set 

The virtual message is displayed if either of the following two conditions 
exist for the SAV file: 

1. Bit 10 (mask 2000) is set in the job status word (location 44) of the 
SAV file. 

2. Location of the SAV file contains the RAD50 value for "VIR" . 

These are the same two conditions that cause TSX-Plus to recognize the SAV file 
as being a virtual image when it is started. 

Examples: 

.R SETSIZ 

*TSTPRG 

Base size of program Is 22Kb 

Size of allocation space is 28Kb 

*SY:PIP 

Base size of program is 10Kb 

Size of allocation space is 22Kb 

*PR0G1 

Base size of program Is 31Kb 

No allocation size specified in SAV file 

Virtual-image flag is set 
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A. 2 Setting total allocation for a SAV file 

The "/T" switch is used to specify the total amount of memory space to be 
allocated for a program when it is run. The form of the /T switch is 
"/T rvalue." where "value" is the number of K-bytes of memory to allocate. 
Note that a decimal point must be specified with the value if it is entered as 
a decimal value. 

If the "/T" switch is used without a value, the effect is to clear the TSX-Plus 
size allocation information in the SAV file. 

Examples: 

.R SETSIZ 
*SY:PIP/T:18. 
*TSTPRG/T:32. 
*PR0G1/T 

A. 3 Setting amount of dynamic memory space 

The "/D" switch is used to specify the amount of dynamic memory space to be 
reserved for a program. The SETSIZ program calculates the total amount of 
space to allocate for the program by adding the static size (stored in location 
50 of the SAV file by LINK) to the specified dynamic size. The form of the /D 
switch is "/Devalue." where "value" is the number of K-bytes of dynamic memory 
space to reserve. If a program does not use any dynamic memory space, the /D 
switch may be used without an argument value to cause the total memory space 
allocation to be set equal to the static size of the program. FORTRAN programs 
use dynamic space for I/O buffers and the exact amount required depends on the 
number of I/O channels used. However, 4Kb of dynamic memory space seems to be 
adequate for most FORTRAN programs. 

Examples e 

.R SETSIZ 
*SY:PIP/D:11. 



*TSTPRG/D:4. 
*PR0G1/D 

A. 4 Setting virtual- image flag in SAV file 

The "/V" switch is used to cause SETSIZ to set the virtual-image flag in the 
SAV file. This flag is bit 10 (mask 2000) in the job status word (location 44) 
of the SAV file. 

Setting this flag indicates that the program will not directly access RM0N, 
although it may do so indirectly by use of the .GVAL and .PVAL EMT's. The 
significance with regard to TSX-Plus is that It allows the program to use more 
than 56Kb (if that much memory is also allowed by use of a MEMORY command). 
The virtual-image flag should not be set unless you are sure the job does not 
need direct access to the RMON area. 
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Appendix B — DIBOL TSX-Plus SUPPORT SUBROUTINES 



A set of subroutines is provided with TSX-Plus to perform DIBOL record locking 
and message transmission functions. DIBOL ISAM files are not supported by 
TSX-Plus. These subroutines may not be used with DBL, which provides most of 
their functionality separately. Note that if these TSX-Plus features are to be 
used, they must be enabled when the TSX-Plus system is generated. 

B.l Record locking subroutines 

The record locking subroutines coordinate access to a common file being shared 
and updated by several TSX-Plus users. The five subroutines parallel the 
operation of the DIBOL statements: OPEN, CLOSE, READ, WRITE and UNLOCK. The 
normal DIBOL I/O statements cannot be used to perform record locking under 
TSX-Plus . 

Opening the file 

The first subroutine is used to open a shared file in update mode. The form of 

the call is: 

XCALL FOPEN(chan,devlbl, errflg) 

where 

chan = A decimal expression that evaluates to a number in the range 

1-15. This is the channel number used in associated calls to FREAD, 

FWRIT, FUNLK and FCLOS subroutines. 

devlbl = The name of an alphanumeric literal, field or record that 
contains the file specification in the general form: dev:f ilnam.ext 

The file size must not be specified with the file name. An optional 
"/W" switch may be appended to the file name to cause the "WAITING 
FOR dev:file" message to be printed. 

errflg = A numeric variable capable of holding at least two digits into 
which is stored an indication of the result of the FOPEN call. The 
following values are returned: 

Value Meaning 



No error. File is open and ready for access. 

17 File name specification is invalid. 

18 File does not exist or channel is already open. 

72 Too many channels are open to shared files. 

Re-gen TSX-Plus and increase the value of MAXSFC parameter. 

73 Too many shared files are open. 

Re-gen TSX-Plus and increase the value of MAXSF parameter. 

The FOPEN subroutine should only be used to open files that will be updated by 
several users. The normal DIBOL OPEN READ /WRITE sequence should be used for 
other files. Several files may be opened for update by calling FOPEN with 
different channel numbers. The ONERROR DIBOL statement does not apply to these 
record locking subroutines. Instead the "errflg" argument is used to indicate 
the outcome of the operation. 
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Locking and reading a record 

The FREAD subroutine is used to lock and read a record. The form of the call 

is: 

XCALL FREAD ( chan, record, rec #,'T' or 'W', errflg) 

where 

chan = Decimal expression in the range 1-15 that identifies a channel 
previously opened by FOPEN. 

record = Name of the record or alphanumeric field in which the record 
read is to be placed. 

rec # = Decimal expression that specifies the sequence number of the 
record to be read. This value must be between 1 and the total number 
of records in the file. 

'T'/'W = If 'T' is specified as the fourth parameter, FREAD will return a 
value of 40 in errflg if the requested record is locked by some other 
user. If 'W is specified, FREAD will wait until the record is 
unlocked by all other users and will never return the record-locked 
error code. 

errflg = Decimal variable into which is stored one of the following 
values: 

Value Meaning 



No error. Record has been locked and read. 

1 End-of-file record has been read. 

22 I/O error occurred on read or channel is not open. 
28 Invalid record number (possibly beyond end of file). 
40 Record locked by another user. 

(Only returned if "T' is specified as fourth argument.) 

71 Channel was not opened by calling FOPEN. 

72 Request to lock too many blocks in file. 

Re-gen TSX-Plus and increase value of MXLBLK parameter. 

The FREAD subroutine functions like the DIBOL READ statement. However, whereas 
the DIBOL READ statement always returns an error code (40) if the requested 
record is locked, FREAD offers the user a choice: If "T" is specified as the 
fourth argument to FREAD, a code of 40 will be returned in errflg if the record 
is already locked. If "W is specified as the fourth argument and the record 
is locked, FREAD does not return an error code, but rather waits until the 
requested record is unlocked. It is much more efficient to wait for a locked 
record by using the 'W option rather than re-executing the FREAD with the "T" 
option. It may be desirable to perform the first FREAD using the 'T option. 
If the record is locked a "WAITING FOR RECORD..." message can be displayed on 
the user's console and another FREAD can be issued with the 'W option to wait 
for the record. On return from this FREAD the "WAITING" message can be erased. 
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Note that although record locking is requested on a record-by-record basis, the 
actual locking is done on a block-wi thin-file basis. (A block contains 512 
characters). The result of this is that a record is locked if any record 
contained in the same block(s) as the desired record is locked. 

Once a record is locked and read using FREAD, the record remains locked until 
the program performs one of the following operations: 

1. Issues an FWRIT to the channel from which the record was read. 

2. Issues another FREAD to the channel. 

3. Issues an FUNLK to the channel. 

4. Issues an FCLOS to the channel. 

5. Terminates execution by use of the STOP statement or because of an 
error. 

The same set of rules that apply to the DIBOL READ statement apply to FREAD. 

Writing a. record 

The FWRIT subroutine is called to write a record to a shared file. The form of 

the call is: 

XCALL FWRIT ( chan, record, rec #, err fig) 

where 

chan = Channel number associated with the file. 

record = Name of the record or alphanumeric field that contains the 
record to be written. 

rec # = Decimal expression that specifies the sequence number of the 
record to be written. 

errflg = Decimal variable into which is stored one of the following 
values. 

Value Meaning 



No error. 
22 I/O error occurred during write or channel is not open. 
28 Bad record number specified. 

The FWRIT subroutine writes the indicated record to the file then unlocks any 
blocks that were locked by the program. FWRIT appends a <CR><LF> to the end of 
the written record as does the DIBOL WRITE statement. The rules for the DIBOL 
WRITE statement also apply to FWRIT. 
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Unlocking records 

The FUNLK subroutine is used to unlock records that were locked by calling 

FREAD. The form of the call is: 

XCALL FUNLK(chan) 

chan = Channel number. 

Closing a shared file 

The FCLOS subroutine is called to close a channel that was previously opened to 

a shared file by calling FOPEN. The form of the call is: 

XCALL FCLOS (chan) 

chan = Channel number. 

FCLOS unlocks any locked records and closes the file. Other users accessing 
the file are unaffected. After calling FCLOS, the channel may be reopened to 
some other file. 

Record Locking Example 

In the following example a program performs the following functions: 

1. Opens a shared file named "INV.DAT" on channel 2. 

2. Reads a record whose record number is stored in RECN into the field 
named ITEM and waits if the record is locked by another user. 

3. Updates the information in the record. 

4. Rewrites the record to the same position in the file. 

5. Closes the shared file. 

XCALL F0PEN(2,'INV.DAT',ERRFL) 
XCALL FREAD (2, ITEM, RECN, 'W',ERRFL) 
;<update record> 
XCALL FWRIT(2,ITEM,RECN,ERRFL) 
XCALL FCLOS (2) 

Modifying programs for TSX-Plus 

It is a straightforward process to modify DIBOL programs to use the TSX-Plus 
record locking subroutines. OPEN, CLOSE, READ, WRITE, and UNLOCK statements 
that apply to shared files must be replaced by the appropriate subroutine 
calls. Error conditions must be tested by IF statements following the 
subroutine calls rather than by using the ONERROR statement. 

B.2 Message communication subroutines 

Three subroutines are included in the DIBOL support package to allow programs 
to transfer messages to each other. When running under TSX-Plus these 
subroutines must be used instead of the DIBOL SEND and RECV statements. 
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Message Channels 

Messages are transferred to and from programs by using TSX-Plus "Message 
Channels". A message channel accepts a message from a sending program, stores 
the message in a queue associated with the channel and delivers the message to 
a receiving program that requests a message from the channel. Message channels 
are totally separate from I/O channels. 

Each active message channel has associated with it a one to six character name 
that is used by the sending and receiving programs to identify the channel. 
The total number of message channels is defined when TSX-Plus is generated. 
The names associated with the channels are defined dynamically by the running 
programs. A message channel is said to be "active" if any messages are being 
held in the queue associated with the channel or if any program is waiting for 
a message from the channel. When message channels become inactive they are 
returned to a free pool and may be reused by another program. 

The DIBOL SEND command directs a message to a program by using the name of the 
receiving program. Under TSX-Plus, a sending program transmits a message using 
an arbitrary channel name. Any program may receive the message by using the 
same channel name when it requests a message. 

Sending a Message 

The MSEND subroutine is called to queue a message on a named channel. If other 
messages are already pending on the channel the new message is added to the end 
of the list of waiting messages. The form of the call is: 

XCALL MSEND(chan, message, errflg) 

where 

chan = alphanumeric literal or variable that contains the 

channel name (1 to 6 characters). 

message = alphanumeric or decimal literal, field or record that contains 
the message to be sent. 

errflg = Decimal variable into which will be stored one of the following 
values: 

Value Meaning 



No error. Message has been sent. 

1 All message channels are busy. (Re-gen TSX-Plus and 
increase the value of MAXMC parameter). 

2 Maximum allowed number of messages are being held in 
message queues. (Re-gen TSX-Plus and increase the value 
of MAXMSG parameter). 

Note that the maximum message length that may be transferred is defined during 
system generation by the MSCHRS parameter. If a message longer than this is 
sent, only the first part of the message will be delivered. 
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Checking for Pending Messages 

The MSGCK subroutine may be called to determine if any messages are pending on 

a named channel. The form of the call is: 

XCALL MSGCK(chan, message, errflg) 

where 

chan = alphanumeric literal or variable that contains the name of the 
channel (1 to 6 characters). 

message = alphanumeric or decimal field or record where the received 
message is to be placed. 

errflg = decimal variable into which will be stored one of the following 
values : 

Value Meaning 



No error. A message has been received. 

3 No message was queued on the named channel. 

If a received message is shorter than the receiving message field the remainder 
of the field is filled with blanks. If the message is longer than the field, 
only the first part of the message is received. 

Waiting for a Message 

The MSGWT subroutine is used by a receiving program to suspend its execution 
until a message is available on a named channel. It is much more efficient for 
a program to wait for a message by calling MSGWT rather than repeatedly calling 
MSGCK. The form of the call is: 

XCALL MSGWT(chan, message, errflg) 

where the arguments have the same meaning as for MSGCK, and the following 
values may be returned in errflg. 

Value Meaning 



No error. A message has been received 

1 All message channels are busy. 



-228- 



DIBOL Subroutines 

Message Examples 

In the following example a program sends a message to another program by using 
a message channel named "SORT" and then waits for a reply to come back through 
a message channel named "REPLY". 

XCALL MSEND( 'SORT' , 'DK: PAYROL.DAT' ,ERRFL) 
IF(ERRFL.NE.O)GO TO ERROR 
XCALL MSGWT( 'REPLY', MS GBF,ERRFL) 
IF(ERRFL.NE.0)GO TO ERROR 

B.3 Using the subroutines 

The subroutines described above are part of the MACRO program called 
"DTSUB.MAC". Once assembled, the object file for DTSUB (DTSUB.OBJ) may be 
linked with DIBOL programs that use the record locking or message facilities. 
An example of a LINK command is shown below. 

.R LINK 

+tvt> rv/~> nnrvn TvnfTTn nT-nnr 

'TRUVJ- ri\UVj, LI1DUD yUJLDKJU 

B.4 Miscellaneous functions 

Determining the TSX-Plus line number 

The TSLIN subroutine can be called to determine the number of the TSX-Plus 

timesharing line from which the program is being run. Real lines are numbered 

^ Arteo/*ii *--i ire* 1 XT o+-^>»+--?rii'v *a -f- T tt-i *-!-»*=* oom^i rwAew *-V» att Ot»^» 0-r^£*j-»-T-p-l«-*yl T.tVi «r»-r-» TC V— *D Inn 

is generated. Detached job lines occur next and virtual lines are numbered 
last. 

The form of the call of TSLIN is: 

XCALL TSLIN (lnum) 

where "lnum" is a numeric variable capable of holding at least two digits into 
which is stored the TSX-Plus line number value. 



-229- 



-230- 



Appendix C — FILTIM PROGRAM 

In addition to the date of creation of a file, TSX-Plus also stores file 
creation times in device directories. At the time a file is closed, the 
current time of day is automatically stored in the sixth word of the directory 
entry for that file. Under RT-11, this word is unused for permanent files and 
contains the job and channel number for tentative file entries. In order to 
represent the time as a positive 16-bit value, the time is converted to an 
integer representing the number of 3 second intervals since midnight. For 
example, if a file were closed at 11:13:22, then the sixth word of the 
permanent directory entry for that file would contain 13467 (32233 octal). 

11 hr * 60 min/hr * 60 sec/min / 3 sec/interval = 13200 

13 min * 60 sec/min / 3 sec/interval = 260 

22 sec / 3 sec/interval = 7 
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An EMT to obtain file directory information, including file creation times is 
provided by TSX-Plus. An EMT is also provided to set the file creation time 
value into file directory entries. See Chapter 7 for information on use of 
these EMTs. 

The DIR utility provided with RT-11 does not interpret file creation time 
information as set by TSX-Plus, so a utility program (FILTIM) is provided with 
TSX-Plus to obtain this information. The FILTIM program should be copied from 
the distribution medium to the system device (SY:). It may then be run either 
explicitly (R FILTIM) or implicitly as a system program (FILTIM). Although 
FILTIM does not accept wildcard file specifications, it will accept up to 6 
file specifications. The default device is "DK" and the default extension is 
"MAC". A device specification also applies to subsequent file specifications 
which do not explicitly include a device. Files created under RT-11 or before 
this feature was implemented in TSX-Plus will have a creation time of 00:00:00. 

Example: 

•FILTIM CKACT TPRMAN.TXT MAN:CH13.DPS APPC.DPS R.K0: FILTIM 



DK:CKACT.MAC 


3P 


31-May-83 


00:00:00 


184 


DK: TPRMAN. TXT 


835 


17-Jul-83 


22:15:33 


14226 


MAN: CHI 3. DPS 


35 


18-Jul-83 


08:31:42 


3570 


MAN:APPC.DPS 


5 


18-Jul-83 


15:54:48 


3605 


RK0: FILTIM. MAC 


23 


18-Jul-83 


11:24:57 


4240 



Note that the default device "DK" is used for CKACT and is carried over to the 
next file specification, and that the default file type is "MAC". The logical 
device "MAN" is used for the next two file specifications until the device 
specification, "RK0". And again, the default extension for RK0: FILTIM is 
"MAC". 

Warning : Due to the method used by PIP for copy operations, file creation times 
are not preserved during copy operations, although the date is handled 
correctly. When copying a file with PIP, the destination file will acquire the 
time the copy is made as its creation time. The EMT to set file times, 
described in Chapter 7, may be used to set the correct time in the new file. 
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Appendix D — RT-11 & TSX-Plus EMT CODES 



D.l TSX-Plus RT-11 Compatible EMTs 



EMT Code Chan Name 



Description 



340 - 




341 




342 




343 - 




344 




345 




346 




347 




350 




351 




352 - 




353 




354 - 




355 




357 - 




374 





374 


1 


374 


2 


374 


3 


374 


4 


374 


5 


374 


6 


i -7 / r\ 


-7 
1 


374 


10 


374 * 


11 


374 


12 


374 - 


13 


375 





375 


1 


375 


<-> 


375 


3 


375 


4 


375 


5 


375 


6 


375 


7 


375 


10 


375 


11 


375 


12 


375 * 


13 


375 


14 


375 - 


15 


375 - 


20 



.TTINR 

.TTYOUT 

.DSTATUS 

. FETCH/. RELEAS 

.CSIGEN 

.CSISPC/.GTLIN 

.LOCK 

.UNLOCK 

.EXIT 

.PRINT 

.SRESET 

.QSET 

. SETTOP 

.RCTRLO 

.HRESET 

.WAIT 

.SPND 

.RSUM 

.PURGE 

.SERR 

.HERR 

.CLOSE 

TIT rtOT/ 

.CHAIN 

.MWAIT 

.DATE 

.ABTIO 

.DELETE 

.LOOKUP 

.ENTER 

.TRPSET 

.RENAME 

.SAVE STATUS 

.REOPEN 

.CLOSE 

.READ[C]IW] 

.WRIT[C][E][W] 

.WAIT 

.CHCOPY 

.DEVICE 

.CDFN 

.GTJB 



Get character from terminal 

Send character to terminal 

Get device information 

Load/Unload device handlers 

Call command string interpreter 

Get command line 

Lock USR in memory 

Allow USR to swap 

Return to monitor 

Display string at terminal 

Software reset 

Increase I/O queue size 

Set program upper limit 

Reset CTRL-0 

Stop I/O then .SRESET 

Wait for I/O completion 

Suspend mainline program 

Resume mainline program 

Free a channel 

Inhibit abort on error 

Enable abort on error 

Close channel 

i-P — —. 4 1 ,»„1, TTCD 

11) LU 1ULR. Ul)£V 

Pass control to another program 

Wait for message 

Get current date 

Abort I/O in progress 

Delete a file 

Open existing file 

Create file 

Intercept traps to 4 and 10 

Rename a file 

Save channel information 

Restore channel information 

Close channel 

Read from channel to memory 

Write from memory to channel 

Wait for I/O completion 

Open channel to file in use 

Load device registers on exit 

Define extra I/O channels 

Get job information 
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EMT Code Chan Name 



Description 



375 
375 
375 
375 
375 
375 
375 
375 



21 .GTIM 

22 .MRKT 

23 .CMKT 

24 .TWAIT 

25 .SDAT[C][W] 

26 .RCVD[C][W] 

27 .CSTAT 
30 .SFPA 

375 31 .PROTECT 

375 31 1 .UN PROTECT 

32 .SPFUN 

33 .CNTXSW 

34 .GVAL 
34 1 .PEEK 
34 2 .PVAL 

34 3 .POKE 

35 .SCCA 

36 .CRRG 
36 1 .ELRG 
36 2 .CRAW 
36 3 .ELAW 
36 4 .MAP 
36 5 .UNMAP 

36 6 .GMCX 

37 .MTSET 
37 1 .MTGET 
37 2 .MTIN 
37 3 .MTOUT 
37 4 .MTRCTO 
37 5 .MTATCH 
37 6 .MTDTCH 
37 7 .MTPRNT 
37 10 .MTSTAT 

40 .SDTTM 

41 .SPCPS 

42 .SFDAT 

43 .FPROT 



375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 
375 



Get time of day 

Schedule completion routine 

Cancel mark time 

Timed wait 

Send data to another job 

Receive data from another job 

Return channel information 

Trap floating point errors 

Control interrupt vector 

Release interrupt vector 

Special device functions 

Context switch 

Get monitor offset value 

Get low memory value 

Change monitor offset value 

Change low memory value 

Inhibit CTRL-C abort 

Create an extended memory region 

Eliminate an extended memory region 

Create a virtual address window 

Eliminate a virtual address window 

Map virtual window to XM region 

Get window mapping status 

Obtain window status 

Set terminal status 

Get terminal status 

Get character from terminal 

Send character to terminal 

Reset CTRL-0 

Lock terminal to job 

Release terminal from job 

Display string at terminal 

Get system status 

Set date and time 

Change mainline control flow 

Change file date 

Change file protection 



Notes: 



Not supported, will cause error. 

Treated as NOP. 

Minor differences, see Chapter 14. 
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D.2 TSX-Plus Specific EMTs 



EMT Codes 



EMT Code Chan Name 



Description 



375 


lOl 




UNLALL 


375 


102 




L0CKW 


375 


103 




TL0CK 


375 


104 




SNDMSG 


375 


105 




GETMSG 


375 


106 




WATMSG 


375 


107 





SPLFRE 


375 


no 





TSXLN 


375 


111 


0/1 ACT0DT 


375 


113 




UNLOCK 


375 


114 





TTOBLK 


375 


115 





TTIBLK 


375 


116 





CKTTIE 


375 


117 





SETTTO 


375 


120 


0/1 


HIEFF 


375 


I2l 




CKWSHR 


375 


122 




SAVSHR 


375 


123 





CKACT 


375 


125 




SHRFIL 


375 


127 





SEND 


375 


132 





STRTDJ 


375 


132 


1 


STATDJ 


375 


132 


2 


ABRTDJ 


375 


133 





DCLBRK 


375 


134 





MOUNT 


375 


135 





DISMNT 


375 


136 





INITPA 


375 


136 


1 


STRTPA 


o -re 


13 6 


o 


ottvdda 
<3 i ui i. n 


375 


136 


3 


HALT PA 


375 


137 





TTYPE 


375 


140 





PHYADD 


375 


140 


1 


PEEKIO 


375 


140 


2 


POKEIO 


375 


140 


3 


BISIO 


375 


140 


4 


BICIO 


375 


140 


5 


MAPIOP 


375 


140 


6 


MAPMON 


375 


140 


7 


LOKLOW 


375 


140 


10 


UNLOKJ 


375 


140 


11 


ATTVEC 


375 


140 


12 


RELVEC 


375 


140 


13 


LOKJOB 


375 


140 


14 


STEALS 



Unlock all blocks 
Wait for locked block 
Try to lock a block 
Send message on named channel 
Get message from named channel 
Wait for message on named channel 
Get number of free spool blocks 
Get line number 
Reset/set ODT activation mode 
Unlock a block 

Send block of text to terminal 
Get block of test from terminal 
Check for terminal input errors 
Set terminal read time-out 
Reset/set high-efficiency mode 
Check for writes to shared file 
Save shared file information 
Check for activation characters 
Declare file for shared access 
Send message to another line 
Start a detached job 

OIltSCK. UCUdCLlCU JOD StauUS 

Abort a detached job 
Establish break sentinel control 
Mount a directory structure 
Dismount a directory structure 
Initiate performance analysis 
Start monitoring performance 

StOtJ monitoring ryQ-rfn-rmanrp 

Terminate performance analysis 

Get terminal type 

Convert virtual to physical address 

Peek into the 1/0 page 

Poke into the 1/0 page 

Bit-set into the I/O page 

Bit-clear into the I/O page 

Map PAR7 to the 1/0 page 

Map PAR7 to simulated RMON 

Lock job into lowest memory 

Unlock job from memory 

Attach to interrupt vector 

Release interrupt vector 

Lock job without re-positioning 

Get exclusive system access 
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EMT Codes 

EMT Code Chan Name 



Description 



375 


140 


15 


RTURNS 


375 


140 


16 


SETPRI 


375 


140 


17 


MAP PHY 


375 


140 


20 


ATT SVC 


375 


140 


21 


SCHCMP 


375 


141 





MEMTOP 


375 


143 





USERTS 


375 


143 


1 


MAPRTS 


375 


144 





JSTAT 


375 


145 




FILINF 


375 


146 




SFTIM 


375 


147 


0/1 


GSUNAM 


375 


150 





SETPRI 


375 


151 




SPHOLD 


375 


152 





SELOPT 


375 


153 





NONINT 



Relinquish exclusive system access 

Set user mode priority level 

Map to physical memory 

Attach interrupt service routine 

Schedule completion routine 

Control size of job 

Associate with run-time system 

Map run-time system into job 

Get job status information 

Get file directory information 

Set file creation time 

Get/set user name 

Set job execution priority 

Set spooler H0LD/N0H0LD 

Select terminal option 

Set [non] interactive job status 
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Appendix E — SUBROUTINES USED IN EXAMPLE PROGRAMS 



E.l PRTOCT - Print an octal value 

The following subroutine accepts a value in RO and prints the 6 digit octal 
representation of that value at the terminal. 

.TITLE PRTOCT 
.ENABLE LC 



; Print octal value of the word in RO 



.MCALL .PRINT 
.GLOBL PRTOCT 



PRTOCT: 


MOV 


R1,-(SP) 




MOV 


R2,-(SP) 




MOV 


R3,-(SP) 




MOV 


#E0W,R2 




MOV 


#6,R3 


1$: 


MOV 


R0,R1 




T» TO 


V LI / / / \J, JS.1 




ADD 


#'0,R1 




MOVB 


Rl,-(R2) 




CLC 






ROR 


RO 




ASH 


#-2,R0 




SOB 


R3,l$ 




. PR.INT 


#CHARS 




MOV 


(SP)+,R3 




MOV 


(SP)+,R2 




MOV 


(SP)+,R1 




RETURN 




CHARS: 


.BLKB 


6 


EOW: 


9 ilU \J JL J. 

.EVEN 
.END 


<200> 



;Save RI-k3 on the stack 



; Point to end of 6 char output buffer 

;Set up counter for 6 chars 

;Set up mask for low 3 bits (Is digit) 

;Get low 3 bits 

; Convert to ASCII 

;Fill octal digits in from end 



; Shift out bits just converted 
; Repeat for 6 chars 
;Display result at console 
;Restore registers R1-R3 



;6 char output buffer 

;No CR terminator for .PRINT 



E.2 PRTDEC - Print a decimal value 

The following subroutine accepts a value in RO and prints the decimal represen- 
tation of that value at the terminal with no leading zeroes. 

.TITLE PRTDEC 
.ENABL LC 

; Print the decimal value of the word in RO 

.MCALL .PRINT 
.GLOBL PRTDEC 



PRTDEC: MOV Rl,-(SP) 



;Save Rl and R2 
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MOV 


R2,-(SP) 




MOV 


//BUFEND, R2 




MOV 


RO,Rl 


1$: 


CLR 


RO 




DIV 


#10., RO 




ADD 


#'0,R1 




MOVB 


R1,-(R2) 




MOV 


R0,R1 




BNE 


1$ 




.PRINT 


R2 




MOV 


(SP)+,R2 




MOV 


(SP)+,R1 




RETURN 






.BLKB 


5 


BUFEND: 


.BYTE 
.EVEN 
.END 


200 



; Point to end of output buffer 

;Set up for DIV 

; Clear high word for DIV 

;Get least significant digit 

;Make remainder into ASCII 

;Save digit in output buffer 

;Set up for next DIV 

;Until nothing left 

; Display number at the terminal 

: Res tore Rl and R2 



;5 char output buffer 

;No CR terminator for .PRINT 



E.3 PRTDE2 - Print a 2 digit decimal value 

The following subroutine accepts a value in RO and prints the decimal represen- 
tation of it at the terminal. The value must be in the range of to 99. 

.TITLE PRTDE2 
.ENABLE LC 

; Print a 2-digit decimal value from RO 



.MCALL 


.PRINT 


.GLOBL 


PRTDE2 


PRTDE2: MOV 


R1,-(SP) 


MOV 


R2,-(SP) 


MOV 


R3,-(SP) 


MOV 


R0,R1 


MOV 


#<BUFFER+2>,R2 


MOVB 


#200, (R2) 


MOV 


#2,R3 


2$: CLR 


R0 


DIV 


#10., R0 


ADD 


#'0,R1 


MOVB 


Rl,-(R2) 


MOV 


R0,R1 


SOB 


R3,2$ 


.PRINT 


#BUFFER 


MOV 


(SP)+,R3 


MOV 


(SP)+,R2 


MOV 


(SP)+,R1 


RETURN 





;Get copy of char in Rl 
; Point to buffer. 
;Set end for .PRINT 

; Clear high word for DIV 

;Get low digit 

;Convert low digit to ASCII 

;Put digit in char buffer 

;Roll quotient for next DIV 

;Two digits only 

;Display the result 
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BUFFER: .BLKB 
.EVEN 
.END 



E.4 PRTR50 - Print a RAD50 word at the terminal 

The following subroutine accepts a one word RAD50 value in RO and prints its 
ASCII representation at the terminal. 

Example: 



.TITLE 


PRTR50 


.ENABL 


LC 


; Display the 


RAD 50 value 


.MCALL 


.TTYOUT 


.GLOBL 


PRTR50 


PRTR50: MOV 


R1,-(SP) 


MOV 


R4,-(SP) 


MOV 


R5,-(SP) 


MOV 


R0,R5 


CLR 


R4 


DIV 


#50, R4 


MOV 


R5,R1 


MOV 


R4,R5 


CLR 


R4 


DIV 


#50, R4 


.TTYOUT 


R50TBL(R4) 


.TTYOUT 


R50TBL(R5) 


.TTYOUT 


R50TBL(R1) 


MOV 


(^sr )-r,Rj 


MOV 


(SP)+,R4 


MOV 


(SP)+,R1 


RETURN 




.NLIST 


BEX 


R50TBL: .ASCII 


/ ABCDEFGH 


.EVEN 




.END 





;Need place to store last char 
;Need R4 and R5 for DIV 

Get copy of rO into dividend 
Zero high word for DIV 
Extract last char 
Save last char (remainder) 
Move quotient for next DIV 
Zero high word for second DIV 
Get first and second chars 
Display first char (quotient) 

and second char (remainder) 

and last char 
Restore registers 



/ ABCDEFGHIJKLMNOPQRSTUVWXYZ$. 0123456789/ 



E.5 DSPDAT - Print a date value at the terminal 

The following subroutine accepts a date value in RO and prints the date 
representation at the terminal. 
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.TITLE DSPDAT 
.ENABL LC 

; Print a date value from RO 

.MCALL .PRINT 

. GLOBL DSPDAT , PRTDEC 

MONMSK = 036000 
DAYMSK = 001740 
YRMSK = 000037 



DSPDAT: MOV 


R1,-(SP) 




MOV 


R0,R1 ;Get copy of date in 


Rl 


BIC 


#~CDAYMSK,RO ;Mask in only day bit 


s (5-9) 


ASH 


#-5,R0 ; Shift down 




CALL 


PRTDEC ; Print it out 




MOV 


R1,R0 ;Get fresh copy of date 


BIC 


#~CMONMSK,R0 ;Use only month bits 


(10-13) 


ASH 


#-7,R0 ; Shift down to index 


into month table 


ADD 


#M0NTBL,R0 ; Point into table 




.PRINT 


RO ; Display the month 




MOV 


R1,R0 ; Fresh copy again 




BIC 


#~CYRMSK,R0 ;Use only year bits 




ADD 


#72., RO ;Year since 1972 




CALL 


PRTDEC ;Display the year 




MOV 


(SP)+,R1 




RETURN 






.NLIST 


BEX 




MONTBL: .ASCII 


/-NON-/<200XOX0> 




.ASCII 


/-Jan-/<200><0><0> 




.ASCII 


/-Feb-/<200><0><0> 




.ASCII 


/-Mar-/<200X0X0> 




.ASCII 


/-Apr-/<200X0X0> 




.ASCII 


/-May-/<200X0X0> 




.ASCII 


/-Jun-/<200X0X0> 




.ASCII 


/-Jul-/<200X0X0> 




.ASCII 


/-Aug-/<200X0X0> 




.ASCII 


/-Sep-/<200><0><0> 




.ASCII 


/-Oct-/<200X0X0> 




.ASCII 


/-Nov-/<200X0X0> 




.ASCII 


/-Dec-/<200X0X0> 




.EVEN 






.END 
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E.6 DSPTI3 2. Display a 3-second format time value 

The following subroutine accepts a special 3-second time value in RO and prints 
the time value at the termina 1 . 

.TITLE DSPTI3 
.ENABL LC 

; Display special 3-sec format time value from RO 



.MCALL 


.TTYOUT 


.GLOBL 


DSPTI3,PRTDE2 


DSPTI3: MOV 


R1,-(SP) 


MOV 


R0,R1 


CLR 


RO 


DIV 


#20. ,R0 


MOV 


R1,-(SP) 


ASL 


Til 

JS.J. 


ADD 


R1,(SP) 


MOV 


R0,R1 


CLR 


RO 


DIV 


#60., RO 


MOV 


R1,-(SP) 


CALL 


PRTDE2 


, TTYOUT 


#': 


MOV 


(SP)+,R0 


/-•ATT 


PRTDE2 


.TTYOUT 


#': 


MOV 


(SP)+,R0 


CALL 


PRTDE2 


MOV 


(SP)+,R1 


RETURN 




.END 





;Set up for divide 

;Get # of 3-SEC'S since midnight 

;Put on stack 

; 2X 3-SEC'S 

;Plus IX gives 3X = seconds 

;Get rest of time 

;Set up for next divide 

;Get number of minutes 

;And save on stack 

;What's left is hours, display 



;Recover minutes 
; Display minutes 

;Recover seconds 



E.7 ACRTI3 -_ Convert a time value to special 3-second format 

The following subroutine accepts a time value from the terminal and converts it 
to a special 3-second internal format. The value is returned in RO. 

.TITLE ACRTI3 
.ENABL LC 

; Accept a time from the keyboard and return it in 
; a special 3— second format in RO 

. GLOBL ACRTI3 

ACRTI3: MOV R1,-(SP) 
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MOV 


R2,-(SP) 




MOV 


R3,-(SP) 




CLR 


HOURS 




CLR 


MINITS 




CALL 


GETNUM 




BCS 


2$ 




MUL 


#<60.*20.>,R3 




MOV 


R3, HOURS 




TST 


NUMERR 




BNE 


1$ 




CALL 


GETNUM 




BCS 


2$ 




MUL 


#20. ,R3 




MOV 


R3, MINITS 




TST 


NUMERR 




BNE 


1$ 




CALL 


GETNUM 




BCS 


2$ 




CLR 


R2 




DIV 


#3,R2 


1$: 


ADD 


MINITS, R2 




ADD 


HOURS, R2 




MOV 


R2,R0 




CLC 






BR 


3$ 


2$: 


SEC 




3$: 


MOV 


(SP)+,R3 




MOV 


(SP)+,R2 




MOV 


(SP)+,R1 




RETURN 




GETNUM: 


CLR 


NUMERR 




CLR 


R3 


1$: 


MOVB 


(R0)+,R1 




CMPB 


R1,#'0 




BLT 


2$ 




CMPB 


Rl,#'9 




BGT 


2$ 




MUL 


#10., R3 




SUB 


#'0,R1 




ADD 


R1,R3 




BR 


1$ 


2$: 


CMPB 


Rl,#': 




BEQ 


3$ 




INC 


NUMERR 




TSTB 


Rl 




BEQ 


3$ 




SEC 






RETURN 




3$: 


CLC 

RETURN 





;Make sure it's reentrant 

Accrue decimal hours 

Return with error 

Convert hours to 3-sec periods 

Save hours in 3-sec units 

Did we hit end of input? 

Yes, return value 

Accrue decimal minutes 

Return with error 

Convert minutes to 3-sec periods 

Save minutes in 3-sec units 

End of input? 

Yes, return value 

Accrue decimal seconds 

Return with error 

Convert seconds into 3-sec periods 

Quotient stays in R2 

Add in 3-secs from minutes 

Add in 3-secs from hours 

Return it in RC 

Say no error 

Return 

Say there was an error 



Say no error yet 

Initialize number 

Get next digit into Rl 

Less than '0? 

Not a digit 

Greater than '9? 

Not a digit 

Shift previous digits 

Convert current digit to binary 

And include in number 

Get digits til next separator 

Is it a legal separator? 

Yes, return 

Say it may be end 

Was it a nul (end of input string)? 

Yes, return 

No, say invalid input 

Error return 

No error 
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HOURS: .WORD 

MINITS: .WORD 

NUMERR: .WORD 
.END 
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Appendix F — TSX-Plus USER ERROR MESSAGES 



Several different categories of errors can generate messages, ranging from 
errors which are fatal to the operating system to something as simple as an 
incorrect file specification. Errors are identified by the name of the program 
which recognized the error and one or more lines of descriptive information. 
Errors identified by utility programs are identified by the name of the utility 
(e.g., ?PIP-F, 7DUP-F, ?KED-F) and may or may not abort the program. For more 
information about utility program error messages, consult the appropriate RT-11 
manual (RT-11 System Message Manual, RT-11 System Utilities Manual, RT-11 
Keypad Editor User's Guide, etc.). Errors which are fatal to the TSX-Plus 
operating system (identified as 7TSX-F) report error conditions for which 
time-sharing users are not usually responsible and usually cannot correct. TSX 
fatal errors should be reported to the system manager who should consult the 
TSX-Plus System Manager's Guide for more information. Errors which are not 
fatal to the operating system but which indicate a user mode error are reported 
as monitor errors. This Appendix describes TSX-Plus specific monitor error 
messages. 

All user mode fatal monitor error messages have the syntax: 

7KM0N-F-" message 

or 

7M0N-F-" message 

where the "7KM0N-F" form is used if the error occurs while using the keyboard 
monitor and the "?MON-F" form is used for errors which occur within a user 
program. In some cases, the message is only informational rather than 
indicating an error. In these cases, the message is of the form: 

7KM0N-I-" message " 

Error messages are consistent with RT-11 usage insofar as possible. Monitor 
error messages unique to TSX-Plus are described below. Consult the RT-11 
System Message Manual for monitor errors not described here. 

Ambiguous option 

Not enough characters were specified to distinguish between options. 

ASSIGN table full 

Maximum number of logical assignments (15 per user) exceeded. SHOW 
ASSIGNS and DEASSIGN unnecessary logical assignments. 

Attempt to increase MAXPRIORITY above current value 

Maximum job priority may be restricted by the system manager. It may be 
reduced, but it may not be increased during a time-sharing session. 

Cannot find SY:TSODT.REL file 

The relocatable copy of the TSX-Plus ODT debugging program was not found 
on the system device. Copy the file "TSODT.REL" from the distribution 
medium to SY. 
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Cannot file SY;TSXUCL.SAV 

A command was attempted to be interpreted as a user-defined command, but 
the TSXUCL program could not be found. Copy TSXUCL.SAV from the distrib- 
ution to SY. 

Cannot open alignment file 

The alignment file specified in a SPOOL align command cannot be opened. 

Canno t open logoff command file 

A logoff command file which was specified during job start-up could not be 
found while logging the job off. 

Cannot open spool device 

The spooler cannot access the spool device. Verify the device name used 
in the SPOOL macro during TSX-Plus generation and check for correct device 
assignments. 

Can^t open system accounting file 

The file SYrACCESS.TSX cannot be found during logon or logoff. This file 
is created by the system manager. 

Closing log file 

If a device on which a terminal output log file is open is initialized or 
squeezed, the log file is first closed. 

Command file nesting too deep 

Maximum depth of command file nesting exceeded. The depth of command file 
nesting allowed depends on the number and length of parameter strings. 
Three levels are possible even with long strings and as many as seven 
levels are possible with no parameters. See Chapter 3 for more infor- 
mation on command files. 

Command file not found 

The specified command file was not found. See Chapter 2 for an explan- 
ation of command interpretation including default devices, and Chapter 3 
for more information on command files. 

Command file parameter string too long 

Total number of characters in parameter string exceeds the maximum allowed 
length of 60 characters. See Chapter 3. 

Command string too complicated 

The command string expansion is too large for the internal CCL buffer. 
Reduce the complexity of the command string. The SET CCL TEST command may 
be used to examine the expanded command string generated by high level 
commands. 



■246- 



Error Messages 

Device is mounted by another user 

The INITIALIZE and SQUEEZE commands are invalid if the device is MOUNTed 
by any other user. This minimizes the opportunity for data corruption 
when other users may be writing to a device. See the INITIALIZE and 
SQUEEZE commands for motivation. 

Device is still mounted by other users 

This informational message is displayed when a DISMOUNT request is issued 
for a device which is also MOUNTed by other users. See the INITIALIZE and 
SQUEEZE commands for motivation. 

Device or file is access restricted 

User does not have access privilege to requested device or file. The 
system manager may restrict user access to individual devices and files. 

Directory I/O error 

A device directory failed internal consistency checks. Devices must have 
valid RT-11 format directories for use with TSX-Plus. This error may also 
occur when attempting to use 22-bit addressing with DMA devices when the 
handler or hardware does not support 22-bit addressing. 

Handler active — Can^t update running copy 

An attempt was made to perform a SET command on a device handler which was 
in use. If the handler is idle when the SET is issued, the change will be 
made, otherwise, the running copy of the handler is not altered. Reissue 
the command when the handler is not active. 

Illegal use of wildcards 

Wildcards may not be specified for (part of) this command. 

IND already active 

The IND program cannot be run from within a command file which is being 
executed under control of the IND program. 

IND is not available 

The IND.SAV program was not on the system disk during TSX-Plus start-up. 
IND is provided with RT-11 version 5 and later. 

Invalid logical disk name 

Logical subset disks must be mounted as LDO through LD7. 

Invalid multiple value on option 

More than one parameter was specified for an option which only accepts 
one. 
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Invalid or uninitialized directory 

A disk device must contain a valid RT-11 format directory to be accessed 
by any operation other than INITIALIZE. Logical subset disks must be 
initialized before first use. This error may also occur when attempting 
to use 22-bit addressing with a DMA device and either the device handler 
or hardware does not support 22-bit addressing. 

Invalid SAV file 

A file specified with an R or RUN command failed internal consistency 
checks. The file may be damaged. An incorrect file type may have been 
specified - the default type is "SAV". 

Invalid address as EMT argument 

An address specified in a monitor call was odd or was not within the job's 
address space. The value returned as the abort location is the address of 
the instruction or the EMT that caused the error. 

Invalid file name 

An invalid file name was specified. Check for typing errors, names too 
long, and correct file specification format. 

Invalid line number 

An invalid line number was specified for a KILL or DETACH command. 

Invalid start address for program 

The start address for the program was outside of the program's memory 
bounds or on an odd address. A MACRO program may have an incorrect 
starting address specified with the .END directive. The file may be 
damaged. An incorrect file type may have been specified - the default is 
"SAV". 

Kernel mode trap within TSX-Plus 

A kernel mode trap error usually indicates the operating system image has 
been corrupted due to hardware or software failure. Record the full error 
message and report the error to the system manager. This error can also 
be generated by attempting to access a non-existent memory address with 
the real-time EMT's to access the I/O page. 

Line is gagged 

Messages cannot be sent to lines which have SET TT GAG unless those lines 
are waiting in TSKMON for a command. 

Line too long 

The expanded CCL command was too long. Commands are expanded into the 
chain data area, locations 500 - 777. See the SET CCL TEST command. 
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Log file overflow 

An error was reported while writing to the terminal output log file. This 
is most commonly an attempt to write past end-of-f ile. Make more room on 
the output device, specify a file size with the SET LOG command, or use 
the SET LOG NOWRITE option to reduce the volume of log file output. 

Logical Disk support was not generated into system 

Attempts to MOUNT a logical subset disk are not valid unless support for 
logical subset disks was selected when generating TSX-Plus. 

Logical disks must be nested in order of increasing unit #_ 

When a file residing within a logical subset disk is to be mounted as 
another logical subset disk, it must be assigned a higher number than the 
outer level logical subset disk. For example, the following command is 
invalid: MOUNT LD1 LD3:MYDISK; whereas the following is acceptable: 
MOUNT LD3 LDl.-MYDISK. 

Max allowed number of devicgj already mounted 

The number of device directories which may be cached is defined during 
system generation. DISMOUNT devices on which caching is no longer needed 
or consult the system manager. 

Memory size change not allowed in non-swapping TSX system 

Jobs may not change size dynamically unless job-swapping was enabled 
during system generation. Consult the system manager. 

Missing equal sign 

The equal sign was missing on a SET device command. 

No defined operator's console 

No operator console was defined during system generation. Form mount 
requests and messages using the OPERATOR command are sent to the operator 
console. 

No free detached job lines 

The maximum number of detached job lines is specified during system 
generation. Either wait for a job to terminate, stop one by use of the 
DETACH/KILL command, or ask the system manager to increase the number of 
detached lines. 

Not enough memory to run program 

A file was too large (or the size specified in the SAV image was too 
large) to fit in the space allocated to the job. See Appendix A for more 
information on program size specifications. Use overlay segments or chain 
requests to reduce the program size. Use the MEMORY command to request 
more memory for your job. Note that you cannot use the MEMORY command in 
a non-swapping environment; see the system manager. 
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Performance monitor is in use by user number nn 

The performance monitor facility is already in use. Only one job may use 
it at a time. 

Priority value must be in the range . . . 



Job priority may not be set less than 0, nor higher than the maximum 
allowed priority. 

Prompt string too long 

Prompt strings may not be longer than 8 characters. 

Save file I/O error 

An I/O error occurred while reading the SAV file. Check that the disk is 
still on line. It is also possible that the SAV file or the directory is 
damaged. 

SL was not included at system generation 

The SET SL ON command may not be issued unless support for the single line 
editor was selected when generating TSX-Plus. 

System was not generated to support performance monitoring 

Performance monitoring is an optional feature that must be included during 
system generation. See the system manager. 

Terminal type must be set to VT100 or VT52 

The SET SL ON command may only be issued if the current terminal type is 
VT100 or VT52. Other terminal types are not supported by the single line 
editor. 

Table overflow 

Too many devices/files have been specified in the ACCESS command. See the 
system manager. 

This command only legal in startup command file 

The ACCESS and SET LOGOFF commands are only valid in startup command 
files. 

This operation not legal with SY (system) device 

The device which was booted when starting TSX-Plus may not be initialized 
or squeezed while running TSX-Plus. If it is necessary to initialize or 
squeeze this device, do so while running RT-11. 

Too many completion routines 

You have attempted to connect too many completion routines to interrupt 
vectors. The number of interrupt vectors that can be connected to 
completion routines is determined during system generation. See the 
system manager. 
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Too many files 

The command interpreter uses standard command string format: up to 6 
input files and 3 output files. Reduce the number of file specifications 
accordingly. 

Too many parameters to command file 

TSX-Plus command files accept a maximum of six parameters. See Chapter 3. 

Trap to 14 

Abort location == nnnnnn 

Invalid breakpoint trap executed. The abort location provided is the 

address of the instruction following the trap. 

Trap to 20 

Abort location =_ nnnnnn 

Invalid IOT instruction executed. The abort location provided is the 

address of the instruction following the trap. 



J.J.CXp LU Jt 



Abort location =_ nnnnnn 

Invalid TRAP instruction executed. The abort location provided is the 
address of the instruction following the trap. 

TSGEN was modified without relinking TSKMON 

Whenever a new TSX-Plus system generation is done, both TSX and TSKMON 
must be relinked. See the system manager. 

Unable to allocate memory for virtual overlays 

The system failed to successfully allocate extended memory regions when 
trying to run a program with virtual overlays. Unlock jobs from memory or 
increase the PLAS region swap file size. 

Unable to open log file 

The system reported an error when attempting to create a file for terminal 
output logging. Check the file specification, verify that there is room 
and that the output device is not write protected. 

User command interface program not available 

The system could not locate the file specified with the command: 
SET KMON UCl[=filnam]. Check the file specification. The default file is 
SY:UKMON.SAV. 

USR called from completion routine 

You cannot call system service routines that use TSUSR from a completion 
routine. This includes: .LOOKUP, .ENTER, .RENAME, .DELETE, .CLOSE, 
.DSTATUS, .SFDAT, and .FPROT. 
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USR err #n 

All of the following USR errors result from consistency checks performed 

in closing a tentative file (creating a permanent file). These are 

usually indicative of a strange hardware condition, such as exchanging or 

squeezing a disk while a file is open. 
USR err # _1 

TSUSR can't find tentative file entry for specified file on close. 
USR err # 2 

File length in channel block is not equal to length in file entry. 
USR err # _3 

Highest block number written is greater than file length. 
USR err _# 4- 

Empty file entry doesn't follow tentative file entry. 
USR err # _5 

Tentative file entry status was lost during close operation. This is 

usually an indication of hardware failure. 

Unrecognizable command 

TSX-Plus could not find a system command, a user-defined command, or a 
command file with that name. See Chapter 2 for more information on 
command interpretation. 

Value required for option 

A command was issued that required a value for an option, but no value was 
specified. Reissue the command correctly. 

You are not authorized to write to that device or file 

The system manager may restrict access to individual devices or files. 
See the system manager. 

You're not privileged for that command 

The command is a privileged command. The system manager may restrict the 
use of privileged commands. 

?CCL-W-This command may interfere with other users 

This warning is issued by CCL on INITIALIZE and SQUEEZE commands to warn 
you that other users using that device might be dismayed by what you are 
about to do. See the warning with the SQUEEZE command. 
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Appendix G — LOGICAL SUBSET DISKS 



Logical subset disks provide a method of logically partitioning a large disk 
into smaller units which can themselves be treated as directory structured 
devices. This is done by creating a (relatively large) file on a physical 
device and then creating a device directory and files within that file. The 
resulting pseudo device which is created within the file on the mother device 
is called a logical subset disk. Logical subset disks may also be nested. 
That is, one logical subset disk may be contained within another logical subset 
disk. This nesting may continue up to seven levels of logical subset disks 
within other logical subset disks. Logical subset disks may be initialized, 
squeezed, and have files created, opened, closed and deleted. They may also be 
assigned logical device names (e.g. OUT:, DK: , ABC:). Several keyboard 
commands are used to manipulate logical subset disks: DISMOUNT, MOUNT, SET LD 
and SHOW SUBSETS. 

Support for logical subset disks is built into the kernel of TSX-Plus. 
Therefore, it is not necessary to use the LD device handler and logical subset 
disks may be used under TSX-Plus with either version 4 or version 5 RT-11 
utilities. 

Logical subset disks are given the device names LDQ through LD7. Each user may 
use all eight logical subset disks at any time. That is, if one user has 
mounted LDO then any other user may also use LDO simultaneously and they need 
not (and usually will not) refer to the same file containing the logical subset 
disk. If logical subset disks are nested, then the device numbers must 
increase with the level of nesting. For example, LDO may contain a file to be 
mounted as LD1. However, a file contained within LD1 may never be mounted as 
LDO, 

The typical sequence of operations when using logical subset disks is to: 1) 
create a file on a physical disk device; 2) mount that file as a logical subset 
disk; 3) initialize the new logical subset disk; 4) and then proceed to use it 
as any other disk device (except that it cannot be physically handled independ- 
ently of the surrounding real disk) . Subsequent uses of the logical disk only 
require that the disk be re-mounted. The file need not be re-created, nor the 
logical subset disk re-initialized. 

The following example shows a typical sequence of commands which might be used 
to initiate use of a new logical subset disk. 

. CREATE DL1:MYDISK.DSK/ALLOCATE:500. 
. MOUNT LDO: DLl:MYDISK 
. INITIAL IZE/NOQUERY LDO: 



.DISMOUNT LDO: 



In order to use this new logical disk at a later time, it would only be 
necessary to issue the MOUNT command: 

.MOUNT LDO: DL1:MYDISK DK: 
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The default (and recommended) file type for files intended to contain logical 
subset disks is .DSK. 

When logical subset disks are mounted, information about them can be obtained 
with the SHOW SUBSETS command. For example: 

. SHOW SUBSETS 

LDTT^-> DL1:MYDISK.DSK[500] 

To remove a logical subset disk from use, use the dismount command. For 
example : 

. ASSIGN DL1 DK 
. DISMOUNT LDO: 

Note that the disk files containing logical subset disks are automatically 
marked as protected files. In order to delete them, they must first be 
unprotected. 

It is possible with logical subset disks to create some unusual situations and 
conflicts. For example, it is possible to mount a logical subset disk and then 
unprotect and delete the file which contained it. This condition would be 
marked with an asterisk (*) with the SHOW SUBSETS command. In addition, the 
SET LD CLEAN command can be used to force the system to compare, verify and 
correct the information in its internal logical subset disk tables if possible. 
Obviously, the system will not go back and recreate deleted files. An implicit 
SET LD CLEAN Is done each time the DUP utility is called (e.g. with the DELETE 
and SQUEEZE commands). 

For more information on the details of the commands used with logical subset 
disks, see the descriptions in Chapter 2 of the following commands: DISMOUNT, 
MOUNT, SET LD CLEAN and SHOW SUBSETS. 
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Appendix H — JOB EXECUTION PRIORITIES 



TSX-Plus jobs may be assigned execution priorities to control their scheduling 
relative to other jobs. The priority values range from to 127. The maximum 
execution priority that may be assigned to a job can be controlled by the 
system manager by use of the TSAUTH account authorization program or the SET 
MAXPRIORITY command (see the TSX-Plus System Manager's Guide). 

The priority assigned to a job is set by use of the SET PRIORITY keyboard 
command or the TSX-Plus EMT described in Ghapter 7. The current priority for a 
job and the maximum authorized priority can be displayed by use of the SHOW 
PRIORITY keyboard command, and may be obtained from within programs with the 
.GVAL request. 

The priority values are arranged in three groups: the fixed-low-priority group 
consists of priority values from up to the value specified by the PRILOW 
sysgen parameter; the fixed-high-priority group ranges from the value specified 
for the PRIHI sysgen parameter up to 127; the middle priority group ranges from 
(PRILOW+1) to (PRIHI-1). The following diagram illustrates the priority 
groups: 
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Job scheduling is performed differently for jobs in the fixed-high-priority and 
fixed-low-priority groups than for jobs with normal interactive priorities. 
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the 
fixed-high-priority group (PRIHI to 127) execute at fixed priority values. 
That is, the priority absolutely controls the scheduling of the job for 
execution relative to other jobs. The job state does not influence the 
execution scheduling except as to whether the job is in a ready-to-run state or 
a wait state. A job with a fixed priority is allowed to execute as long as it 
wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The 
fixed-low-priority group is intended for use by very low priority background 
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tasks. Normal time-sharing jobs should not be assigned priorities in either of 
the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be 
used by normal, interactive, time-sharing jobs. Jobs with these assigned 
priorities are scheduled in a more sophisticated manner than the fixed-priority 
jobs. In addition to the assigned priority, external events such as terminal 
input completion, I/O completion, and timer quantum expiration play a role in 
determining the effective scheduling priority. For these jobs the job state is 
the primary factor in determining execution scheduling and the user-assigned 
job priority only influences the scheduling of jobs in the same state. See 
Chapter 5 of the TSX-Plus System Manager's Guide for further information about 
job scheduling. 

When a job with a normal priority switches to a virtual line, the priority of 
the disconnected job is reduced by the amount specified by the PRIVIR sysgen 
parameter. This causes jobs that are not connected to terminals to execute at 
a lower priority than jobs that are. This priority reduction does not apply to 
jobs with priorities in the fixed-high-priority group or the fixed-low-priority 
group. The priority reduction is also constrained so that the priority of 
normal jobs will never be reduced below the value of (PRILOW+1). 
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.ABTIO, 215 
.CDFN, 215 
.CHAIN, 215 
.CHCOPY, 215 
.CNTXSW, 215 
.CSIGEN EMT, 78 
.CSISPC EMT, 78 
.DEVICE, 215 
.DEVICE EMT, 185 
.FETCH, 215 
.FORK, 215 
.GTJB, 215 
.GTLIN EMT, 78 

Checking I/O page mapping, 170 
Special TSX-Plus use, 112 

.HRESET, 215 

.INTEN, 215 

.LOCK, 215 
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.MWAIT, 216 
.PEEK, 172, 216 
.POKE, 172, 216 
.PROTECT, 202, 216 
.PURGE 

Shared files and, 151 
,QSET, 216 
.RCVD,' 216 
.RELEAS, 216 
.RSUM, 183 
. SAVESTATUS 

Shared files and, 151 
.SDAT, 216 
.SDTTM, 216 

.SETTOP, 111, 216, 219 
.SFPA, 216 
.SPND, 183 
.SRESET, 216 
.SYNCH, 217 
.TLOCK, 217 
.TTINR, 217 
.TTYIN EMT 

Command file input, 78 

Non-wait input, 59, 105 

Time-out value, 124 
.UNLOCK, 217 
»UNPROTECT» 217 
ABORT command, 73 
Aborting jobs 

Detached jobs, 85 

Normal jobs , 36 



ACCESS command, 28 

ACRTI3, 241 

Activation characters, 97 

Checking for, 128 

Defining, 103 

Field width, 104 

0DT activation mode, 135 

Resetting, 104 

Time-out activation, 124 
Adapting RT-11 Real-time programs, 

202 
Administrative control, 3 
Alignment of forms, 96 
ASSIGN command, 28 
Assigns 

Displaying those in effect, 62 
B(ASE) command, 73 

Backing up in a spool file, 92 
BACKUP command, 29 
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BATCH facility, 217 
Block locking 

See Shared files 
BOOT command, 29, 73 
Booting the system, 73 
Break sentinel control, 125 
BYE command, 29 
CACHE 

SHOW command, 63 
CACHE parameter 

Selecting appropriate size, 46 
Caching 

Data, 160 

Directories, 38 
Carriage-return 

Automatic line-feed, 106 
Cataloged procedures 

See Command files 
Chapter summaries, 4 
Character echoing, 57, 103 
CLOSE command, 73 
COBOL command, 29 
Command file control, 75 
Command files, 75 

Comments within, 77 

Control characters within, 78 

Controlling input, 78, 104 

Controlling listing, 58, 77, 78 

Displaying messages, 79 

Invoking, 17, 18, 76 

Nesting of, 77 
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Parameter strings, 76 

PAUSE command, 41 

Pausing execution, 79 

Setting error abort level, 48 
Command interpreter, 17 
Commands 

Defining, 20 

Listing user-defined, 63 
Common data areas, 203 
COMPILE command, 30 
Completion routine 

Connecting to an interrupt, 196 

Scheduling, 201 
Configuration 

SHOW command, 63 
Configuration requirements, 1 
Control characters, 11 

Ctrl-C, 11, 103 

Ctrl-0, 11 

Ctrl-Q, 11, 58, 59, 106 

Ctrl-R, 11 

Ctrl-S, 11, 58, 59, 106 

Ctrl-U, 11 

Ctrl-W, 11, 81 

Ctrl-Z, 11 

Within command files, 78 
Control files 

See Command files 
Cooperative file access 

See Shared files 
COPY command, 30 
CORTIM 

SHOW command, 63 
CORTIM parameter 

Setting value, 47 
CREATE command, 30 
CRT terminal support, 58 
D(EPOSIT) command, 73 
Data caching, 160 

Enabling use of, 148 

Setting number of cache buffers, 
53 

Suppression of, 160 
DATE command, 31 
DBL default compiler, 50 
DEASSIGN command, 31 
Debugging programs, 42 
Deferred character echoing, 57 



DELETE command, 31 
DELETE key 

Rubout filler character, 102 
DETACH command, 31, 83, 84, 85 
Detached jobs, 81, 82 

Aborting, 32, 85, 87 

Checking status, 32 

Checking status of, 84, 88 

Comparison with virtual lines, 
83 

Control EMTs for, 85 

Keyboard control commands, 31 

Starting, 31, 83, 85 
Device spooling 

See Spooling 
DIB0L command, 32, 73 
DIBOL default compiler, 50 
DIB0L record locking procedures, 

147 
DIBOL support subroutines, 223 
DIFFERENCES command, 32 
Directory caching, 38 

Dismounting a file structure, 
123 

Displaying mounted devices, 65 

Mounting a file structure, 122 

SQUEEZE command effect, 69 
DIRECTORY command, 32 
Directory information 

EMT to obtain, 136 
DISMOUNT command, 33, 253 
Dismounting a file structure, 123 
DISPLAY command, 34, 79 
DL-11, 1 
DSPDAT, 239 
DSPTI3, 241 
DUMP command, 34 
DZ-11, 1 

E(XAMINE) command, 73 
Echo control, 57, 103 
EDIT, 47 

EDIT command, 34 
Editor 

Selecting default, 47 

Single line, 12 
EMT codes 

table, 233 
EMT differences, 215 
EMT tracing, 47 
EMT's 

TSX-Plus specific, 107 
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Error messages, 245 
Escape character 

Within command files, 78 
Escape sequence processing, 102 
Exclusive access to a file, 147 
Exclusive system control, 180 

releasing, 180 
EXECUTE command, 34 
Execution priority, 255 

Virtual lines, 81, 82 
Extended memory regions, 143 
Field width activation, 104 
Field width limit for TT input, 

106 
File 

Block locking, 147 

Data caching, 160 

Exclusive access, 147 

Opening for shared access, 147 

Protection modes, 147 

Shared access, 147 
File creation time, 138 
File directory information, 136 
Fixed-high-priority 

Determining, 112 
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Determining, 112 
Floating point, 216 
Foreground programs 

See Real-time support 
Form alignment procedure, 96 
FORM command, 34, 95 
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Form names, 90, 95 
FORMAT program, 217 
FORTRAN command, 35 
FRUN command, 73 
Generalized data cache 

Selecting appropriate size, 46 
GET command, 73 
Global data areas, 203 
GT ON/OFF command, 73 
Hardware requirements, 1 
Hazeltine terminal support, 58 
HELP command, 35 
High-efficiency terminal mode, 42, 

100, 101, 104, 132 
HIPRCT 

SHOW command, 64 



HIPRCT parameter 

Setting value, 48 
1/0 page 

Accessing, 145, 169 
IND 

Command file aborting, 48, 49 

Command file processing, 49 

Control of command files, 75 
INITIALIZE command, 35 
INSTALL command, 73 
Interactive jobs 

Selecting dynamically, 120 
Interprogram communication, 163 

Checking for messages, 165 

Common memory areas , 203 

Message channels, 163 

Sending a message, 163 

Waiting for a message, 166 
Interrupt completion routine, 196 
Interrupt processing 

(Diagram), 190 
Interrupts 

Connecting to real-time jobs, 
188 
INTI0C 

SHOW command 65 
INTIOC parameter, 49 
Introduction, 1 
10 abort handling, 49 
Job number 

Determining, 112 
Job priority 

Determining, 112 

Maximum, 52 

Setting, 53, 117, 186 

SHOW command, 66 
Job scheduling, 2 
Job status information, 114 
Job status word 

Non-wait TT input, 59, 105 

Setting virtual flag with SETSIZ, 
221 

Virtual-image flag, 143 
K52, 47 

Virtual lines, 82 
KED, 47 

Virtual lines, 82 
Keyboard commands, 17, 28 

Abbreviation of, 17 
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Keyboard monitor 

Prompt character, 54 
KILL command, 36 
KJOB command, 36 
LA120 terminal support, 58 
LA36 terminal support, 58 
LD 

Handler, 217 
LD handler, 253 
Lead-in character, 99, 101 

Determining, 112 
LIBRARY command, 36 
Line number 

Determining, 108 

Determining primary, 112 
Line- feed 

Echoing of, 106 

Ignored with tape mode, 59, 106 
LINK command, 36 

/XM switch, 143 
LOAD command, 73 
Locking a form on a spooled device, 

90 
Locking a job in memory, 182 
Log off command files, 52 
Logging off, 10, 40 
Logging on, 9 

Password, 9 

Project programmer number, 9 

User name, 9 

Virtual lines, 81 
Logging terminal output, 51 
Logical device names, 28 

Assigning, 62 
Logical subset disks 

Dismounting, 33 

Mounting, 39 

Nesting, 253 

Using, 253 

Verifying, 51 
Lower-case character input, 58, 

103 
MACRO command, 37 
MAKE command, 37 
Mapping virtual region, 178 
Maximum priority 

Determining, 112 

Setting, 52 



Memory 

Using as pseudo-disk, 145 
Memory allocation 

EMT to control, 111 

MEMORY command, 37 

Setting size in SAV file, 219 
MEMORY command, 37, 112, 219 
Memory mapping, 141 
Memory space 

Displaying value, 65 
Message channels, 163 
Message communication 

See Interprogram communication 
Messages 

error, 245 

Inhibiting, 57 

Sending to another line, 121 
Modification of shared files 

Checking for, 159 
MONITOR command, 38, 207 
MOUNT command, 38, 122, 253 
Mounting a file structure, 38, 122 
Multi-terminal EMTs, 215 
MUNG command, 40 
Non-interactive jobs 

Selecting dynamically, 120 
Non-wait TT input, 59, 105 
Normal programs, 143 
NUMDC parameter 

Setting value, 53 

SHOW command, 66 
Obtaining TSX-Plus system values, 

112 
ODT activation mode, 135 
0DT debugger, 217 
OFF command, 40, 82 
Opening, shared files, 147 
OPERATOR command, 40 
Operator communication, 40 
Operator privilege 

Determining, 112 

Real-time jobs, 169 
Optimization 

SET SIGNAL, 54 
Page length control, 58 
Paint character 

See Rubout filler character 
Paper tape mode 

See Tape mode 
PAR 7 mapping 

Determining s 112 
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Parameter strings for command files, 

76 
Password 

Changing , 9 

Logging on, 9 
PAUSE command, 41, 79 
Performance monitor, 207 

Control EMT's, 209 

Displaying results, 208 

MONITOR command, 38, 207 

Starting, 207, 209 
Physical address calculation, 184 
Physical address space, 141 
Physical memory access, 178 
PLAS support, 143 
Poke EMT, 174 
Primary line 

Determining, 112 
PRINT command, 4i 
Printer form names, 90 
Priorities, 255 
Priority 

Maximum, 52 
PRIORITY 

SHOW command, 66 
Priority level 

Setting, 53, 117 

setting, 186 
PRIORITY parameter 

Setting value, 53 
PRIVIR parameter, 118, 187, 256 
Program controlled terminal options 

CC ICXiUXUax LUUL1U1 

Programmed Logical Address Space 

See PLAS support 
Programmer number 

Determining, 112 
Project number 

Determining, 112 
PROTECT command, 41 
Protected access to a file, 147 
PRTDE2, 238 
PRTDEC, 237 
PRT0CT, 237 
PRTR50, 239 

Pseudo-disk in memory, 145 
QUAN values 

Selecting, 54 
QUANxx parameters 

Setting value, 54 



SHOW command, 66 

QUEMAN, 217 

QUEUE, 217 

R command, 41 

/DEBUG switch, 42, 112 
/HIGH switch, 42 
/LOCK switch, 42 
/NONINTERACTIVE switch, 43 
/SINGLECHAR switch, 43, 105 
Implicit, 18 

Read time-out value for TT inputs, 
124 

Real-time completion routine, 196 

Real-time jobs 

Operator privilege, 169 

Real-time priority, 197 

Real-time support, 169 

Accessing the I/O page, 169, 172 

177 
Adapting RT-11 programs, 202 
Device reset on exit, 185 
Interrupt connections, 188 
Locking a job in memory, 182 
Mapping to physical addresses, 
178 

Physical address calculation, 
184 

Poke EMT, 174 

Suspending/resuming execution, 
183 
Rebooting the system, 73 
Record locking, 147 
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REENTER command, 73 
Reentrant run-times 

See Shared run-time systems. 
Regions in extended memory, 143 
Releasing exclusive system control, 

180 
REMOVE command, 73 
RENAME command, 44 
Requesting exclusive system control, 

180 
RESET command, 44, 70, 73 
Resident run-times 

See Shared run-time systems. 
RESORC, 217 
Restrictions 

Keyboard commands, 73 

Programs not supported, 217 
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RESUME command, 73 
RMON 

Real-time support consideration, 
170 

Simulated, 143 

SYSGEN options word, 107 
RT-11 

Returning control to, 72, 73 
Rubout filler character, 102 
RUN command, 44 

/DEBUG switch, 42, 112 

/HIGH switch, 42 

/LOCK switch, 42 

/NONINTERACTIVE switch, 43, 120 

/SINGLECHAR switch, 43, 105 
Run-time systems 

See Shared run-time systems. 
Running programs, 41, 44 
SAVE command, 73 
Scheduling a completion routine, 

201 
Scheduling of jobs, 2 
Scope type terminal support, 58 
SEND command, 44 
Sending messages, 121 
SET command, 45, 73 

CACHE, 46 

CCL, 46 

CORTIM, 47 

EDIT, 47 

EMT, 47 

ERROR, 48 

Handler options, 45 

HIPRCT, 48 

IND, 49 

INTI0C, 49 

10, 49 

KMON, 24, 49 

LANGUAGE, 50 

LD, 51, 253 

LOG, 51 

LOGOFF, 52 

MAXPRIORITY, 52 

NUMDC, 53 

PRIORITY, 53 

PROMPT, 54 

QUANxx, 54 

SIGNAL, 54 

SL, 55 

TERMINAL, 56 



TT, 56 

TT ADM3A, 57 

TT DECWRITER, 57 

TT DEFER, 57 

TT DIABLO, 57 

TT ECHO, 57 

TT FORM, 57 

TT F0RM0, 57 

TT GAG, 57 

TT HAZELTINE, 58 

TT LA120, 58 

TT LA36, 58 

TT LC, 58 

TT PAGE, 58 

TT QUIET, 58, 77 

TT QUME, 58 

TT SCOPE, 58 

TT SINGLE, 58 

TT TAB, 59 

TT TAPE, 59, 106 

TT terminal-type, 109 

TT VT100, 59 

TT VT50, 59 

TT VT52, 59 

TT WAIT, 59 

UCI, 24 

UCI=filnam, 24 

UCL, 21, 60 

UCL FIRST, 21, 60 

UCL LAST, 21, 60 

UCL MIDDLE, 21, 60 

UCL NONE, 21, 60 

VM, 61 

WILDCARDS, 61 
SET UCL command 

FIRST, 17 

LAST, 18 

MIDDLE, 17 

NONE, 19 
SETSIZ program, 112, 219 
Setting processor priority level, 

186 
Shared access to a file, 147 
Shared files, 147 

Checking for modification of, 
159 

Opening, 147 

Protection modes, 148 

Saving channel status, 151 

Testing for locked blocks, 156 
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Unlocking a block, 158 

Unlocking all locked blocks, 159 

Waiting for locked block, 154 
Shared run-time systems, 203 

Associating with job, 203 

Displaying run-times available, 
67 

Mapping into job region, 144, 
205 
SHOW command, 62 

ALL, 62 

ASSIGNS, 62 

CACHE, 63 

COMMANDS, 63 

CONFIGURATION, 63 

CORTIM, 63 

DEVICES, 64 

HIPRCT, 64 

INTIOC, 65 

JOBS, 65 

MEMORY, 65 

MOUNTS, 65 

NUMDC, 66 

PRIORITY, 66 

QUANxx, 66 

/-kTTCTTC CI 

IIU£iU£j, US 

RUN-TIMES, 67 

SUBSETS, 67, 253 

TERMINALS, 68 

USE, 68 
SHUTDOWN command, 73 
Signaling 

System tuning parameters, 54 
Simulated RMON 

Access through page 7, 143 

Real-time support consideration, 
170 
Single character activation, 43, 

58, 97, 105 
Single line editor, II 

SET options, 55 
Skipping forward in a spool file, 

91 
SL, 12 

Handler, 217 

SET command, 55 
Special Chain Exit, 24 
SPOOL command, 69, 90 

Aligning a form, 91 

Backing up in a spool file, 92 



Checking device status, 92 
Deleting queue entries, 91 
HOLD & N0H0LD options, 93 
SING & MULT options, 92 
Skipping forward in a file, 91 
Specifying a form name, 90 
Spooling, 89 

Aligning a form, 91 
Backing up in a file, 92 
Checking device status , 92 
Concept of, 89 
Deleting queue entries, 91 
Directing output to, 89 
Displaying requests in queue, 
67 

Form names, 95 

Holding output, 93 

Number of free spool blocks, 134 

Single and multifile processing, 

92 
Skipping forward in a file, 91 
Specifying a form name, 90 
Specifying default form name, 

34 
SPOOL command, 69 

SQUEEZE command, 69 
SRUN command, 73 
START command, 73 
Start-up command file, 9 
Starting detached jobs, 83 
STOP command, 72 
Stopping the system, 72, 73 
Summaries of chapters, 4 
SUSPEND command, 73 
SYSGEN options word, 107 
SYSTAT command, 70 
System configuration 

Showing, 63 
System device 

Determining, 112 
System resource management, 2 
System tuning 

SET SIGNAL, 54 
System values 

Obtaining, 112 
Tab character support, 59 
Tape mode, 59, 106 
TEC0, 47 

MAKE command, 37 
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Use within command files, 78 
TECO command, 71 
Terminal control, 97 

Break sentinel, 125 

Character echoing, 103 

Checking for activation, 128 

Checking for input errors, 127 

Command file input, 104 

Defining activation characters, 
103 

Disabling virtual line use, 103 

Echo control, 103 

Field width activation, 104 

Field width limit, 106 

High-efficiency mode, 104, 132 

Line-feed echoing, 106 

Lower-case character input, 103 

Non-wait TT input, 105 

ODT activation mode, 135 

Read time-out value, 124 

Resetting activation characters, 
104 

Rubout filler character, 102 

Single character activation, 105 

Tape mode, 106 

Transparency mode output, 104 

VT52 & VT100 escape sequences, 
102 
Terminal handler, 97 
Terminal logging, 51 
Terminal options 

Setting, 132 
Terminal type 

Determining, 109 
TIME command, 72 

Time-out value for TT reads, 124 
Transparency mode output, 104 
TS0DT debugging program, 42 
TSX-Plus 

Determining if under, 107 
TSX-Plus license number 

Determining, 112 
TSXPM program, 207, 208 
TSXUCL file 

Size, 112 



TSXUCL program, 23 
Tuning parameters 

Selecting, 54 
TYPE command, 72 
UCL, 20 

UCL command, 72 
UNLOAD command, 73 
Unlocking a job from memory, 183 
UNPR0TECT command, 72 
Unrecognizable command, 18 
USE command, 72 

User Command Interface, 17, 24 
User Command Language, 20 
User name 

changing, 110 

determining, 110 

Logging on, 9 
User-defined commands, 20 

Order of interpretation, 17, 18, 
19 

SHOW command, 63 
Utilities 

Unsupported, 217 
Virtual lines, 81 

Comparison with detached jobs, 
83 

Disabling use of, 103 

Execution priority of, 81 

KED and K52, 82 

Switching to, 11 
Virtual memory, 141 
Virtual programs, 143 

Setting flag with SETSIZ, 221 
Virtual region mapping, 178 
Virtual to physical address, 141, 

184 
Virtual windows, 144 
VM 

Handler, 145, 217 

Initializing, 145 

SET BASE command, 145 
VT100 support, 59, 102 
VT52 support, 59, 102 
WHO command, 72 
X-off 

See Control characters, Ctrl-S. 
X-on 

See Control characters, Ctrl-Q. 
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